ClickHouse/doc/reference/en/quotas.rst

96 lines
4.1 KiB
ReStructuredText
Raw Normal View History

2017-04-27 08:07:20 +00:00
Quotas
2017-04-03 19:49:50 +00:00
======
2017-04-27 08:07:20 +00:00
Quotas allow you to limit resource usage over a period of time, or simply track the use of resources.
Quotas are set up in the user config. This is usually ``users.xml``.
2017-04-03 19:49:50 +00:00
2017-04-27 08:07:20 +00:00
The system also has a feature for limiting the complexity of a single query (see the section "Restrictions on query complexity").
2017-04-03 19:49:50 +00:00
2017-04-27 08:07:20 +00:00
In contrast to query complexity restrictions, quotas:
* place restrictions on a set of queries that can be run over a period of time, instead of limiting a single query.
* account for resources spent on all remote servers for distributed query processing.
2017-04-03 19:49:50 +00:00
2017-04-27 08:07:20 +00:00
Let's look at the section of the ``users.xml`` file that defines quotas.
2017-04-03 19:49:50 +00:00
.. code-block:: xml
2017-04-27 08:07:20 +00:00
<!-- Quotas. -->
2017-04-03 19:49:50 +00:00
<quotas>
2017-04-27 08:07:20 +00:00
<!-- Quota name. -->
2017-04-03 19:49:50 +00:00
<default>
2017-04-27 08:07:20 +00:00
<!-- Restrictions for a time period. You can set multiple time intervals with various restrictions. -->
2017-04-03 19:49:50 +00:00
<interval>
2017-04-27 08:07:20 +00:00
<!-- Length of time. -->
2017-04-03 19:49:50 +00:00
<duration>3600</duration>
2017-04-27 08:07:20 +00:00
<!-- No restrictions. Just collect data for the specified time interval. -->
2017-04-03 19:49:50 +00:00
<queries>0</queries>
<errors>0</errors>
<result_rows>0</result_rows>
<read_rows>0</read_rows>
<execution_time>0</execution_time>
</interval>
</default>
2017-04-27 08:07:20 +00:00
By default, the quota just tracks resource consumption for each hour, without limiting usage.
2017-04-03 19:49:50 +00:00
.. code-block:: xml
2017-04-27 08:07:20 +00:00
<statbox>
<!-- Restrictions for a time period. You can set multiple time intervals with various restrictions. -->
<interval>
<!-- Length of time.-->
<duration>3600</duration>
<queries>1000</queries>
<errors>100</errors>
<result_rows>1000000000</result_rows>
<read_rows>100000000000</read_rows>
<execution_time>900</execution_time>
</interval>
<interval>
<duration>86400</duration>
<queries>10000</queries>
<errors>1000</errors>
<result_rows>5000000000</result_rows>
<read_rows>500000000000</read_rows>
<execution_time>7200</execution_time>
</interval>
</statbox>
2017-04-03 19:49:50 +00:00
2017-04-27 08:07:20 +00:00
For the ``statbox`` quota, restrictions are set for every hour and for every 24 hours (86,400 seconds). The time interval is counted starting from an implementation-defined fixed moment in time. In other words, the 24-hour interval doesn't necessarily begin at midnight.
2017-04-03 19:49:50 +00:00
2017-04-27 08:07:20 +00:00
When the interval ends, all collected values are cleared. For the next hour, the quota calculation starts over.
2017-04-03 19:49:50 +00:00
2017-04-27 08:07:20 +00:00
Let's examine the amounts that can be restricted:
2017-04-03 19:49:50 +00:00
2017-04-27 08:07:20 +00:00
``queries`` - The overall number of queries.
2017-04-03 19:49:50 +00:00
2017-04-27 08:07:20 +00:00
``errors`` - The number of queries that threw exceptions.
2017-04-03 19:49:50 +00:00
2017-04-27 08:07:20 +00:00
``result_rows`` - The total number of rows output in results.
2017-04-03 19:49:50 +00:00
2017-04-27 08:07:20 +00:00
``read_rows`` - The total number of source rows retrieved from tables for running a query, on all remote servers.
2017-04-03 19:49:50 +00:00
2017-04-27 08:07:20 +00:00
``execution_time`` - The total time of query execution, in seconds (wall time).
2017-04-03 19:49:50 +00:00
2017-04-27 08:07:20 +00:00
If the limit is exceeded for at least one time interval, an exception is thrown with a text about which restriction was exceeded, for which interval, and when the new interval begins (when queries can be sent again).
2017-04-03 19:49:50 +00:00
2017-04-27 08:07:20 +00:00
Quotas can use the "quota key" feature in order to report on resources for multiple keys independently. Here is an example of this:
2017-04-03 19:49:50 +00:00
.. code-block:: xml
2017-04-27 08:07:20 +00:00
<!-- For the global report builder. -->
<web_global>
<!-- keyed - the quota_key "key" is passed in the query parameter, and the quota is tracked separately for each key value.
For example, you can pass a Metrica username as the key, so the quota will be counted separately for each username.
Using keys makes sense only if quota_key is transmitted by the program, not by a user.
You can also write <keyed_by_ip /> so the IP address is used as the quota key.
(But keep in mind that users can change the IPv6 address fairly easily.) -->
<keyed />
2017-04-03 19:49:50 +00:00
2017-04-27 08:07:20 +00:00
The quota is assigned to users in the ``users`` section of the config. See the section "Access rights".
2017-04-03 19:49:50 +00:00
2017-04-27 08:07:20 +00:00
For distributed query processing, the accumulated amounts are stored on the requestor server. So if the user goes to another server, the quota there will "start over".
2017-04-03 19:49:50 +00:00
2017-04-27 08:07:20 +00:00
When the server is restarted, quotas are reset.