Managing Resource Monitors

A virtual warehouse is charged Snowflake credits for each hour (or portion of an hour) that it runs. The number of credits charged depends on the size of the warehouse and how long it runs.

To help control costs and avoid unexpected credit usage related to using warehouses, Snowflake provides resource monitors. Resource Monitors can be used by account administrators to impose limits on the number of Snowflake credits that warehouses can use within each monthly billing period. Resource monitors provide fine-grained control, allowing limits to be applied selectively to specific roles.

In this Topic:

Overview

A resource monitor is a dictionary object in Snowflake. It consists of the following properties:

Credit quota:

The number of Snowflake credits allocated to the monitor for each monthly billing period.

Credit usage:

The number of Snowflake credits used during the current monthly billing period.

Triggers:

A trigger specifies a credit quota threshold (as a percentage) and an action to perform when the threshold is reached. If credit usage reaches the threshold within the monthly billing period, the trigger fires and the action is performed. The following actions are supported:

  • Suspend a warehouse once the statements being executed by the warehouse have completed.
  • Suspend a warehouse immediately, which aborts any statements being executed by the warehouse at the moment.

A monitor can have multiple triggers, but must have at least one trigger to perform any actions (i.e. suspending warehouses).

Each monitor can be associated with one or more warehouses; however, a warehouse can only be associated with a single monitor. The association of warehouses and resource monitors is controlled through object access privileges granted to roles.

The credit usage for a resource monitor reflects the sum of all credits used by all warehouses associated with the monitor during the current billing period.

If a monitor reaches its quota for the month and a suspend action has been triggered for the monitor, any warehouses associated with the monitor cannot be resumed until one of the following conditions is met:

  • A new monthly billing cycle starts.
  • The credit quota for the monitor is increased.
  • The credit threshold for the monitor trigger is increased.
  • The warehouse is no longer associated with the monitor.
  • The monitor is dropped.

Resource Monitor DDL

Snowflake provides the following DDL commands for creating, managing, and using resource monitors:

In addition, the following commands can be used to associate resource monitors with warehouses and view the associated monitors:

Creating Resource Monitors

Note

Only account administrators (i.e. users with the ACCOUNTADMIN role) can create resource monitors.

This section provides examples of using the CREATE RESOURCE MONITOR command to create a resource monitor:

  • The first example creates a monitor named limit1 that suspends all associated warehouses when the quota of 1000 credits is reached within the month:

    USE ROLE ACCOUNTADMIN;
    
    CREATE OR REPLACE RESOURCE MONITOR limit1 WITH CREDIT_QUOTA=1000
      TRIGGERS ON 100 PERCENT DO SUSPEND;
    

    The SUSPEND action waits for currently-executing queries to finish before suspending the warehouse. This means that a query started before the trigger was activated continues to use credits even after the quota is reached.

  • To avoid warehouses using credits after the quota has been reached, use SUSPEND_IMMEDIATE. For example:

    USE ROLE ACCOUNTADMIN;
    
    CREATE OR REPLACE RESOURCE MONITOR limit1 WITH CREDIT_QUOTA=1000
      TRIGGERS ON 100 PERCENT DO SUSPEND
               ON 120 PERCENT DO SUSPEND_IMMEDIATE;
    

    In this example, the associated warehouses are suspended when 100% usage is reached, which prevents the warehouses from executing any new queries, but allows currently-executing queries to complete. If the currently-executing queries reach 120% usage, the warehouses are suspended immediately, canceling the queries.

Associating Resource Monitors with Warehouses

Granting Resource Monitor Usage to Roles (Required)

A resource monitor is associated with a warehouse by granting the USAGE privilege for the monitor to the role that owns the warehouse, as illustrated in the following diagram:

Resource monitors associated with one or more warehouses

In this diagram:

  • Resource Monitor 1 controls the credits used by Warehouse 1, Warehouse 2, and Warehouse 3.
  • Resource Monitor 2 controls the credits used by Warehouse 4.

Attention

The ACCOUNTADMIN role has implicit USAGE privileges on the resource monitors it creates and, therefore, owns. As a result, if ACCOUNTADMIN is also the owner of any warehouses, all resource monitors owned by ACCOUNTADMIN are automatically associated with these warehouses. This can lead to the scenario described in the following section, in which Snowflake randomly selects the resource monitor used to control the credit usage for each of these warehouses.

To avoid this scenario, we recommend that ACCOUNTADMIN does not own warehouses; however, if ACCOUNTADMIN does own warehouses in your account, we recommend that you explicitly assign a resource monitor to each warehouse, as described in the following section.

Example

The following example creates a resource monitor named limit1 and grants usage for the monitor to myrole, then uses myrole to create warehouse mywh so that the warehouse is associated with the monitor:

USE ROLE ACCOUNTADMIN;

CREATE OR REPLACE RESOURCE MONITOR limit1 WITH CREDIT_QUOTA=10000
   TRIGGERS ON 100 PERCENT DO SUSPEND;

GRANT USAGE ON RESOURCE MONITOR limit1 TO ROLE myrole;

USE ROLE myrole;

CREATE WAREHOUSE mywh;

Explicitly Assigning a Resource Monitor to a Warehouse (Optional)

In addition to granting the USAGE privilege to a role, you can explicitly assign a resource monitor to a warehouse. To explicitly assign a resource monitor to a warehouse, specify the RESOURCE_MONITOR property when creating or altering the warehouse (using CREATE WAREHOUSE or ALTER WAREHOUSE).

Explicitly assigning a monitor to a warehouse is particularly useful if a role owns multiple warehouses and has multiple monitors associated with it. In this scenario, if a monitor isn’t explicitly assigned to each warehouse, Snowflake randomly assigns one of the monitors to control the credit usage of each warehouse. By explicitly assigning a monitor to a warehouse, you specify the monitor that controls the credit usage for the warehouse.

The following diagram illustrates a single role (Role 4) that owns multiple warehouses (Warehouse 5 and Warehouse 6) and has been granted USAGE privilege on multiple monitors (Resource Monitor 3 and Resource Monitor 4):

Single role with multiple warehouses and resource monitors

To ensure appropriate credit usage for each warehouse:

  • Warehouse 5 is explicitly assigned Resource Monitor 3.
  • Warehouse 6 is explicitly assigned Resource Monitor 4.

Tip

We recommend avoiding ambiguity when associating warehouses and resource monitors, by either ensuring each role is granted USAGE for only a single resource monitor or using the RESOURCE_MONITOR property to explicitly assign a monitor to a warehouse.

Example

The following example uses the warehouse (mywh) and resource monitor (limit1) created in the previous example:

ALTER WAREHOUSE mywh SET RESOURCE_MONITOR = limit1;

Note

The role (myrole) that owns the warehouse (mywh) must already have USAGE granted on the monitor (limit1), otherwise an error is returned when assigning the monitor to the warehouse.

Modifying Resource Monitors

Use the ALTER RESOURCE MONITOR command to modify an existing monitor. Modification of a resource monitor is limited to the role that owns the monitor (typically the ACCOUNTADMIN role). You can modify the monthly credit quota for a monitor, as well as replace the triggers for the monitor.

The following example changes the monthly credit quota for limit1 to 2000:

ALTER RESOURCE MONITOR limit1 SET
   CREDIT_QUOTA=2000;

Viewing Resource Monitors

To view all the resource monitors defined for your account, use the SHOW RESOURCE MONITORS command.

To view the warehouses in your account and the resource monitor, if any, associated with each warehouse, use the SHOW WAREHOUSES command.

Common Use Cases for Enforcing Credit Quotas

This section describes two common scenarios for managing credit quotas using resource monitors.

Defining a Global Quota for Your Account

A global credit quota for an account can be implemented by ensuring that all warehouses are associated with a single resource monitor. To accomplish this, grant the USAGE privilege for the resource monitor to the predefined PUBLIC role.

For example:

CREATE RESOURCE MONITOR accountmax WITH CREDIT_QUOTA=10000
  TRIGGERS ON 100 PERCENT DO SUSPEND;

GRANT USAGE ON RESOURCE MONITOR accountmax TO ROLE PUBLIC;

Creating a Quota for a Group of Users

To limit the credit usage for a group of users without restricting other users, you can use multiple roles.

For example:

  1. Create two roles (e.g. restricted1 and unrestricted1)
  2. Create a resource monitor (e.g. limit1).
  3. Grant USAGE on the resource monitor to one of the roles (e.g. restricted1) to ensure that all warehouses created or owned by users with this role are associated with the resource monitor.
  4. Grant the restricted1 role (or a role that has been granted the restricted1 role) to any user who should be subjected to the quota. All other users must be granted the other role (unrestricted1).
USE ROLE ACCOUNTADMIN;

CREATE ROLE restricted1;

CREATE ROLE unrestricted1;

CREATE OR REPLACE RESOURCE MONITOR limit1 WITH CREDIT_QUOTA=10000
   TRIGGERS ON 100 PERCENT DO SUSPEND;

GRANT USAGE ON RESOURCE MONITOR limit1 TO ROLE restricted1;

GRANT ROLE restricted1 TO USER user1;

GRANT ROLE unrestricted1 TO USER user2;
GRANT ROLE unrestricted1 TO USER user3;
GRANT ROLE unrestricted1 TO USER user4;