Activating Budgets and creating custom budgets

To use the Budgets feature, activate the account budget and create custom budgets to monitor credit usage for a group of specific Snowflake objects.

Activating the account budget

To start using Budgets to monitor credit usage for your account, activate the account budget. After you activate the account budget, you can set the spending limit for the account and the email addresses to receive notifications when credit usage is expected to exceed the spending limit.

You can activate the account budget by using Snowsight or SQL.

Create a custom role to manage the account budget

You can create a custom role to activate and modify the account budget. A user who is granted this role can act as the budget administrator and can take the following actions on the account budget:

  • Activate and deactivate the account budget.

  • Set the spending limit.

  • Edit notification settings.

  • Monitor credit usage for the account.

For a full list of roles and privileges required for the budget administrator role, see Budgets roles and privileges.

For example, create role account_budget_admin and grant the role the ability to monitor and manage the account budget:

USE ROLE ACCOUNTADMIN;

CREATE ROLE account_budget_admin;

GRANT APPLICATION ROLE SNOWFLAKE.BUDGET_ADMIN TO ROLE account_budget_admin;

GRANT IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE TO ROLE account_budget_admin;
Copy

Activate and set up the account budget using Snowsight

Note

Only a user with the ACCOUNTADMIN role or a role granted account budget admin privileges can activate and set up the account budget.

  1. Sign in to Snowsight.

  2. Select Admin » Cost Management.

  3. Select Budgets.

  4. If prompted, select a warehouse.

  5. In the upper-right corner of the dashboard, select Set up Account Budget.

  6. Enter the target spending limit for the account.

  7. Enter the email addresses to receive notification emails.

    Note

    Each email address added for budget notifications must be verified. The notification email setup fails if any email address in the list is not verified.

  8. Select Finish Setup.

When you add email addresses for notifications using Snowsight, Snowflake creates an email notification integration in a background process and performs the following actions:

  • Creates a new email notification integration named default_budget_notification_integration using the email addresses you entered to receive notification emails.

  • Grants the USAGE privilege on the integration to the SNOWFLAKE application.

Activate and set up the account budget using SQL

Note

Only a user with the ACCOUNTADMIN role or a role granted account budget admin privileges can activate and set up the account budget.

  1. Activate the account budget using the account_root_budget!ACTIVATE method:

    CALL snowflake.local.account_root_budget!ACTIVATE();
    
    Copy
  2. Set the spending limit using the <budget_name>!SET_SPENDING_LIMIT method:

    CALL snowflake.local.account_root_budget!SET_SPENDING_LIMIT(1000);
    
    Copy
  3. Create a notification integration with the email addresses to receive budget notifications.

    Note

    Each email address added for budget notifications must be verified. The email notification setup fails if any email address in the list is not verified.

    This step is optional. If you have an existing notification integration with verified email addresses in the ALLOWED_RECIPIENTS list, skip to the next step.

    CREATE NOTIFICATION INTEGRATION budgets_notification_integration
      TYPE=EMAIL
      ENABLED=TRUE
      ALLOWED_RECIPIENTS=('costadmin@example.com','budgetadmin@example.com');
    
    Copy

    For more information about creating a notification integration, see Creating an email notification integration.

  4. Grant the USAGE privilege on the notification integration to the SNOWFLAKE application. The USAGE privilege enables the budget to use the notification integration to send emails:

    GRANT USAGE ON INTEGRATION budgets_notification_integration
      TO APPLICATION snowflake;
    
    Copy
  5. Set the email notification for the account budget using the <budget_name>!SET_EMAIL_NOTIFICATIONS method:

    CALL snowflake.local.account_root_budget!SET_EMAIL_NOTIFICATIONS(
       'budgets_notification_integration',
       'costadmin@example.com, budgetadmin@example.com');
    
    Copy

After you activate and set up the account budget, you can enable a non-administrator user to monitor the account budget by using a custom role. For more information, see Create a custom role to monitor the account budget.

Creating a custom budget

You can create a custom budget using Snowsight or SQL.

Create a custom role to create budgets

You can use a custom role to create budgets in your account. For a full list of privileges and roles that must be granted to a role to create a custom budget, see Budgets roles and privileges.

For example, create a budget_owner role and grant the required role and privileges to create custom budgets in schema budgets_db.budgets_schema. The following example must be executed using the ACCOUNTADMIN role:

USE ROLE ACCOUNTADMIN;
   
CREATE ROLE budget_owner;
  
GRANT USAGE ON DATABASE budgets_db TO ROLE budget_owner;
GRANT USAGE ON SCHEMA budgets_db.budgets_schema TO ROLE budget_owner;

GRANT DATABASE ROLE SNOWFLAKE.BUDGET_CREATOR TO ROLE budget_owner;

GRANT CREATE SNOWFLAKE.CORE.BUDGET ON SCHEMA budgets_db.budgets_schema
  TO ROLE budget_owner;
Copy

If you want to enable a role other than the budget owner to modify a custom budget’s settings, you can create a custom role with modify privileges. For more information, see Create a custom role to manage a custom budget.

Create a custom budget using Snowsight

Note

If the account budget is not activated or has been deactivated, you can’t use Snowsight to create custom budgets. However, you can create custom budgets using SQL.

  1. Sign in to Snowsight.

  2. Select Admin » Cost Management.

  3. Select Budgets.

  4. In the upper-right corner of the dashboard, select Plus icon (Add Budget).

  5. Enter a Budget name.

  6. Select the database and schema in which to create your budget.

  7. Enter the Spending limit.

  8. Enter the email addresses to receive notifications.

    Note

    Each email address added for budget notifications must be verified. The notification email setup fails if any email address in the list is not verified.

  9. Select Resources to monitor.

    • To add a database, expand Databases to select a database.

    • To add objects in a schema, expand the schema to list available objects. Expand the object category (for example, Tables or Tasks) to select objects.

    • To add a warehouse, expand Warehouses and select a warehouse.

    Note

    • When you select a database or schema, all supported objects (for example, tables) contained within the database or schema are also added to the budget.

    • You can only add an object to one custom budget. If an object is currently included in one custom budget and you add that object to a second custom budget, Budgets removes the object from the first custom budget without issuing a warning.

When you add email addresses for notifications using Snowsight, Snowflake creates or updates an email notification integration named default_budget_notification_integration in a background process. If the notification integration exists, Snowflake adds any new email addresses you entered to the existing email addresses in the list.

If the notification integration does not exist, Snowflake creates it and grants the USAGE privilege. For more information, see the steps outlined in the account budget section.

After you create and set up a custom budget, you can create a custom role to enable non-account administrators to monitor budget resources and usage. For more information, see Create a custom role to monitor a custom budget.

Create a custom budget using SQL

Create a custom budget and then set the spending limit and notification email addresses.

Note

  1. Review the existing budgets in your account:

    Note

    The following statement returns the budgets for which you have access privileges. Only a user with the ACCOUNTADMIN role can see all the budgets in the account.

    SELECT SYSTEM$SHOW_BUDGETS_IN_ACCOUNT();
    
    Copy
  2. Create budget my_budget in budgets_db.budgets_schema using the CREATE BUDGET command:

    USE SCHEMA budgets_db.budgets_schema;
    
    CREATE SNOWFLAKE.CORE.BUDGET my_budget();
    
    Copy
  3. Set the monthly spending limit. For example, set the spending limit to 500 credits per month:

    CALL my_budget!SET_SPENDING_LIMIT(500);
    
    Copy
  4. Set the notification integration and the email addresses:

    Note

    • If you haven’t already created an email notification integration, see the steps in the account budget section to create one.

    • To send notifications, the SNOWFLAKE application must be granted the USAGE privilege on the notification integration:

      GRANT USAGE ON INTEGRATION budgets_notification_integration
        TO APPLICATION snowflake;
      
      Copy
    CALL my_budget!SET_EMAIL_NOTIFICATIONS('budgets_notification_integration',
                                           'costadmin@example.com');
    
    Copy

After you create and set up a custom budget, you can create a custom role to enable non-account administrators to monitor budget resources and usage. For more information, see Create a custom role to monitor a custom budget.

To add objects to your new budget, see Adding and removing objects from a custom budget.

Create a custom role to manage a custom budget

To monitor and modify a custom budget, you can grant privileges and instance roles to a custom role. For a full list of privileges and roles that must be granted to a role to modify a custom budget, see Budgets roles and privileges.

Examples

Grant the custom role budget_admin the ability to monitor and modify the budget my_budget in schema budgets_db.budgets_schema:

Note

Only a role with the OWNERSHIP privilege on the custom budget can execute the following examples.

  1. For example, grant the required privileges and instance role to custom role budget_admin for budget my_budget in schema budgets_db.budgets_schema:

    GRANT USAGE ON DATABASE budgets_db TO ROLE budget_admin;
    
    GRANT USAGE ON SCHEMA budget_db.budgets_schema TO ROLE budget_admin;
    
    GRANT SNOWFLAKE.CORE.BUDGET ROLE budgets_db.budgets_schema.my_budget!ADMIN
      TO ROLE budget_admin;
    
    GRANT IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE TO ROLE budget_admin;
    
    Copy
  2. Grant the APPLYBUDGET privilege on objects to be added to or removed from a custom budget. This step is required for each object to be added or removed.

    For example, to enable the role budget_admin to add database db1 to custom budget my_budget, execute the following statements:

    GRANT USAGE ON DATABASE db1 TO ROLE budget_admin;
    
    GRANT APPLYBUDGET ON DATABASE db1 TO ROLE budget_admin;
    
    Copy

    To modify the objects in a custom budget, see Adding and removing objects from a custom budget.

Adding and removing objects from a custom budget

You can add or remove objects from a custom budget using Snowsight or SQL.

Note

To add or remove objects from a custom budget, you must use a role with the required privileges on the budget and the object. For more information, see Create a custom role to manage a custom budget.

Add or remove objects from a custom budget using Snowsight

  1. Sign in to Snowsight.

  2. Select Admin » Cost Management.

  3. Select Budgets.

  4. Select the budget to edit.

  5. In the upper-right corner of the dashboard, select Pencil icon (edit icon).

  6. Select + Resources.

    • To add or remove a database, expand Databases to select or deselect a database.

    • To add or remove objects in a schema, expand the schema to list available objects. Expand the object category (for example, Tables or Tasks) to select or deselect objects.

    • To add or remove a warehouse, expand Warehouses and select or deselect a warehouse.

    Note

    • When you select a database or schema, all supported objects (for example, tables) contained within the database or schema are also added to the budget.

    • You can only add an object to one custom budget. If an object is currently included in one custom budget and you add that object to a second custom budget, Budgets removes the object from the first custom budget without issuing a warning.

  7. Select Done.

Add or remove objects from a custom budget using SQL

The role used to add or remove an object from a budget must have the APPLYBUDGET privilege on the object. For more information, see the examples in the Create a custom role to manage a custom budget section.

To review the list of objects already in the custom budget, call the budget’s <budget_name>!GET_LINKED_RESOURCES method. For example, to see the list of objects in the budget my_budget in the budgets_db.budgets_schema schema, execute the following statement:

CALL budgets_db.budgets_schema.my_budget!GET_LINKED_RESOURCES();
Copy

The statement returns the following output:

+-------------+-----------------+-----------+-------------+---------------+
| RESOURCE_ID | NAME            | DOMAIN    | SCHEMA_NAME | DATABASE_NAME |
|-------------+-----------------+-----------+-------------+---------------|
|         326 | DB1             | DATABASE  | NULL        | NULL          |
|         157 | MY_WH           | WAREHOUSE | NULL        | NULL          |
+-------------+-----------------+-----------+-------------+---------------+

Objects must be added to or removed from a budget by reference.

  1. You can add table t1 to budget my_budget by using the following steps:

    1. Grant the APPLYBUDGET privilege on the table to the role budget_admin by executing the following statement:

      GRANT APPLYBUDGET ON TABLE t1 TO ROLE budget_admin;
      
      Copy
    2. Pass a reference for table t1 to the ADD_RESOURCE instance method by executing the following statement:

      CALL budgets_db.budgets_schema.my_budget!ADD_RESOURCE(
         SYSTEM$REFERENCE('TABLE', 't1', 'SESSION', 'applybudget'));
      
      Copy

      The SYSTEM$REFERENCE function creates a reference for a TABLE object, t1, with the APPLYBUDGET privilege granted on the table. This enables the budget to monitor the specified object in your account. The third parameter to the function specifies the scope for the reference; in this case, ‘SESSION’ creates a reference with session scope. References passed to the ADD_RESOURCE method for a budget can be created with any transient reference scope (that is, the third parameter can be either ‘SESSION’ or ‘CALL’).

      For a full list of objects and privileges, see Supported object types and privileges for references.

      Note

      You can only add an object to one custom budget. If an object is currently included in one custom budget and you add that object to a second custom budget, Budgets removes the object from the first custom budget without issuing a warning.

  2. You can remove the database db1 from the budget my_budget by using the following steps:

    1. Grant the APPLYBUDGET privilege on the database to the role budget_admin by executing the following statement:

      GRANT APPLYBUDGET ON DATABASE db1 TO ROLE budget_admin;
      
      Copy
    2. Remove the database by passing a reference to the REMOVE_RESOURCE instance method:

      CALL budgets_db.budgets_schema.my_budget!REMOVE_RESOURCE(
         SYSTEM$REFERENCE('DATABASE', 'db1', 'SESSION', 'applybudget'));
      
      Copy

Creating a custom role to monitor budgets

You can delegate budget monitoring by creating a custom role that can be used by non-administrator users to monitor budgets.

Create a custom role to monitor the account budget

You can create a custom role to enable non-account administrator users to monitor the account budget. For a full list of privileges and roles that must be granted to a role to monitor the account budget, see Budgets roles and privileges.

Example

Note

Only an account administrator can execute the statements in this example.

For example, create role account_budget_monitor and grant the role the ability to view credit usage for the account budget:

USE ROLE ACCOUNTADMIN;

CREATE ROLE account_budget_monitor;
 
GRANT APPLICATION ROLE SNOWFLAKE.BUDGET_VIEWER TO ROLE account_budget_monitor;

GRANT IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE TO ROLE account_budget_monitor;
Copy

Create a custom role to monitor a custom budget

You can create a custom role to enable non-account administrator users to monitor custom budgets. For a full list of privileges and roles that must be granted to a role to monitor a custom budget, see Budgets roles and privileges.

Example

Note

Only a budget owner (a role with the OWNERSHIP privilege) can execute the statements in this example.

Use the budget owner role to grant the custom role budget_monitor the ability to monitor the budget my_budget in schema budgets_db.budgets_schema:

USE ROLE custom_budget_owner;

GRANT USAGE ON DATABASE budgets_db TO ROLE budget_monitor;

GRANT USAGE ON SCHEMA budget_db.budgets_schema TO ROLE budget_monitor;

GRANT SNOWFLAKE.CORE.BUDGET ROLE budgets_db.budgets_schema.my_budget!VIEWER
  TO ROLE budget_monitor;

GRANT IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE TO ROLE budget_monitor;
Copy

Monitoring budgets

You can monitor budgets using Snowsight or SQL.

Monitoring budgets using Snowsight

You can view current and historical budget spending using the Budgets page in Snowsight.

Note

Only a user with the ACCOUNTADMIN role or a role granted the required privileges and role can monitor budgets using Snowsight.

You can view current and historical budget spending using the Budgets page in Snowsight.

  1. Sign in to Snowsight.

  2. Select Admin » Cost Management.

  3. Select Budgets.

In the Current Month view for a budget, you can review the credit usage per day up to the current day. You can see whether you might exceed your budget for the month. The bar graph continues to the end of the month with your projected credit usage based on your actual credit usage for the month. The Spending limit line indicates the spending limit at which a budget notification is triggered.

Budgets projected spending graph

Select Clock icon (months to display) to filter the view by Current Month or longer time periods.

You can compare the Spend (current credit usage) to Interval (time left in the current month) to see if your spending is outpacing your monthly budget.

You can filter the view by selecting Budgets icon Budgets or Resources icon Resources:

  • You can select a custom budget in the Budgets view for details on a specific budget.

    Note

    The Service Type list for a custom budget includes an Unused Resources type. This service type is displayed when an object in a budget has no credit usage data to display. This can happen if the object has no credit usage for compute costs, or if you recently added an object to a budget and the serverless background task has not yet executed.

  • In the Resources view, you can filter and sort by Service Type, object Name, and Credit Usage.

Monitoring budgets using SQL

To monitor the account budget, you must have the required privileges. For more information, see Create a custom role to monitor the account budget.

Use the account_budget_monitor role to view the spending history for the account budget:

USE ROLE account_budget_monitor;

CALL snowflake.local.account_root_budget!GET_SPENDING_HISTORY(
  TIME_LOWER_BOUND => DATEADD('days', -7, CURRENT_TIMESTAMP()),
  TIME_UPPER_BOUND => CURRENT_TIMESTAMP()
);
Copy

You can monitor the spending history by service type. To view the spending history for the search optimization serverless feature for the account budget in the past week, execute the following statements:

USE ROLE account_budget_monitor;

CALL snowflake.local.account_root_budget!GET_SERVICE_TYPE_USAGE(
   SERVICE_TYPE => 'SEARCH_OPTIMIZATION',
   TIME_DEPART => 'day',
   USER_TIMEZONE => 'UTC',
   TIME_LOWER_BOUND => DATEADD('day', -7, CURRENT_TIMESTAMP()),
   TIME_UPPER_BOUND => CURRENT_TIMESTAMP()
);
Copy

To monitor a custom budget, you must have the required privileges. For more information, see Create a custom role to monitor a custom budget.

Use the budget_monitor role to view spending history for a custom budget. For example, to view the spending history for custom budget na_finance_budget in schema budgets_db.budgets_schema, execute the following statements:

USE ROLE budget_monitor;

CALL budgets_db.budgets_schema.na_finance_budget!GET_SPENDING_HISTORY(
  TIME_LOWER_BOUND => DATEADD('days', -7, CURRENT_TIMESTAMP()),
  TIME_UPPER_BOUND => CURRENT_TIMESTAMP()
);
Copy

You can monitor the spending history by service type. For example, to view the spending history for the materialized views included in the budget, execute the following statements:

USE ROLE budget_monitor;

CALL budgets_db.budgets_schema.na_finance_budget!GET_SERVICE_TYPE_USAGE(
   SERVICE_TYPE => 'MATERIALIZED_VIEW',
   TIME_DEPART => 'day',
   USER_TIMEZONE => 'UTC',
   TIME_LOWER_BOUND => DATEADD('day', -7, CURRENT_TIMESTAMP()),
   TIME_UPPER_BOUND => CURRENT_TIMESTAMP()
);
Copy

For more information, see Budget methods.

Deactivating the account budget

You can deactivate the account budget using Snowsight or SQL.

Deactivating the account budget resets the account budget to its state before activation:

  • All historical account budget data is deleted.

  • The background measurement task for the account budget is suspended.

  • The account budget settings for spending limit and email notifications are reset.

Account budget deactivation does not affect custom budgets. To remove a custom budget from your account, use the DROP BUDGET command.

Note

If the account budget is deactivated, you can’t create new custom budgets using Snowsight. However, you can continue to create custom budgets using SQL.

Deactivate the account budget using Snowsight

You can deactivate the account budget using the Budgets page:

  1. Sign in to Snowsight.

  2. Select Admin » Cost Management.

  3. Select Budgets.

  4. Select the more menu in the upper right.

  5. Select Deactivate account budget.

Deactivate the account budget using SQL

You can use the account_root_budget!DEACTIVATE method to deactivate the account budget:

CALL snowflake.local.account_root_budget!DEACTIVATE();
Copy