How to Fix "Quota Exceeded" Errors in ClickHouse

How do I resolve “Quota exceeded” in ClickHouse?

“Quota exceeded” means the session, user, or role has consumed more resources than allowed by the assigned ClickHouse quota rules.

Welcome to the Galaxy, Guardian!
You'll be receiving a confirmation email

Follow us on twitter :)

Oops! Something went wrong while submitting the form.

Description

Example H2

Example H3

Why does ClickHouse return “Quota exceeded”?

The engine fires this error when a query would surpass limits defined in CREATE QUOTA or ALTER QUOTA. Counters include queries, errors, read/write rows, or execution time.

How can I inspect current quota usage?

Query the system.quotas_usage and system.quotas tables. They show remaining allowance and the exact interval that was breached.

How do I create a quota?

Use CREATE QUOTA. Define time intervals (second, minute, hour, day, month) and maximum counts per metric.Apply the quota to one or more roles.

How do I alter an existing quota?

Run ALTER QUOTA to add, change, or drop limits without disconnecting users. Changes take effect immediately.

How do I assign a quota to users?

Create a ROLE, grant it to users, then attach the quota to that role.Quotas always work through roles—even if it is the automatically created role = user name.

Best practices for quota management

Set generous read limits for analytics, strict write limits for ingestion, and isolate automated jobs in their own roles.Monitor system.quotas_usage daily.

Example: limit API consumer to 1 M rows per day

The example below caps SELECT result rows for the api_consumer role to one million every 24 hours, protecting production capacity.

How do I reset quota counters?

Counters reset automatically at the end of each interval.To unblock immediately, broaden the limit with ALTER QUOTA or move the user to a different role.

Troubleshooting tips

If a user still sees the error after limits were raised, make sure the session’s current_roles list includes the updated role and that distributed_ddl_task has finished propagating.

Why How to Fix "Quota Exceeded" Errors in ClickHouse is important

How to Fix "Quota Exceeded" Errors in ClickHouse Example Usage


-- Allow each support agent to run up to 200 SELECTs and return up to 1M rows per hour on the Orders data
CREATE ROLE support_agent;
GRANT SELECT ON Orders, OrderItems TO support_agent;

CREATE QUOTA support_hourly
    KEYED BY user_name
    FOR INTERVAL 1 HOUR
        MAX queries = 200,
        MAX result_rows = 1000000
    TO support_agent;

How to Fix "Quota Exceeded" Errors in ClickHouse Syntax


CREATE QUOTA quota_name
    [KEYED BY {user_name | ip_address | client_key | all}] 
    FOR INTERVAL n {SECOND | MINUTE | HOUR | DAY | MONTH}
        MAX {queries | errors | result_rows | read_rows | execution_time}
    [,...]
    TO role1, role2;

ALTER QUOTA quota_name
    FOR INTERVAL ... MAX ... ;

-- Ecommerce example: cap daily sales dashboard usage
CREATE ROLE analytics_user;
GRANT SELECT ON ecommerce.* TO analytics_user;

CREATE QUOTA analytics_daily
    KEYED BY user_name
    FOR INTERVAL 1 DAY MAX result_rows = 5000000
    TO analytics_user;

Common Mistakes

Mistake: Setting a quota but forgetting to attach it to a role. Result: users stay unlimited. Fix by appending "TO some_role" or altering the quota to include the role.
Mistake: Using KEYED BY ip_address when users connect from dynamic IPs. Result: counters reset unexpectedly. Fix by KEYED BY user_name or client_key.