Tutorial: Get started with budgets¶

Introduction¶

This tutorial introduces you to account-level credit usage monitoring with Budgets by setting up the account budget and creating a custom budget that monitors a group of specified objects.

With budgets, you can monitor credit usage for the compute costs of supported objects, including credit usage for background maintenance tasks and serverless features. Budgets enables you to set a monthly spending limit for each budget and sends a notification email when your current spending is projected to exceed the monthly spending limit.

You can complete this tutorial using a worksheet in Snowsight or using a CLI client such as SnowSQL. Some portions of this tutorial can be completed using Snowsight.

By the end of this tutorial, you will learn how to do the following:

• Create custom roles to monitor and manage budgets.

• Grant the required privileges to add objects to a custom budget.

• Activate and set up an account budget.

• Create a custom budget and add objects to it.

Create a notification integration¶

Budgets use a notification integration to send notification emails when current credit usage is expected to exceed the monthly spending limit. The ALLOWED_RECIPIENTS list must include the verified email addresses of the users to receive budgets notifications.

A notification integration is required if you are completing the tutorial using SQL. Follow the steps below to create one.

When you use Snowsight to set up a budget, the notification integration is automatically created for you. If you are going to use Snowsight to set up your budgets, you can skip to the next step.

1. Execute the following statement to create a notification integration. Use your verified email address in the ALLOWED_RECIPIENTS list:

   USE ROLE ACCOUNTADMIN;
   
   CREATE NOTIFICATION INTEGRATION budgets_notification_integration
     TYPE=EMAIL
     ENABLED=TRUE
     ALLOWED_RECIPIENTS=('<YOUR_EMAIL_ADDRESS>');
   

   Copy

2. After you create the notification integration, grant the USAGE privilege to the SNOWFLAKE application. This privilege is required in order for Budgets to use the notification integration to send emails.

   Execute the following statement to grant the USAGE privilege on the notification integration:

   GRANT USAGE ON INTEGRATION budgets_notification_integration
     TO APPLICATION snowflake;
   

   Copy

Create a database, schema, and custom roles¶

In this step, the following objects are created for the tutorial to create, manage, and monitor budgets:

• A database and schema in which to create custom budgets.

• A custom role to manage the account budget.

• A custom role to monitor the account budget.

• A custom role to create custom budgets.

1. Create a database and schema in which to create a custom budget using the following steps:

   SQLSnowsight

   1. Create the database and schema in which to create the custom budget:

      USE ROLE ACCOUNTADMIN;
      
      CREATE DATABASE budgets_db;
      
      CREATE SCHEMA budgets_db.budgets_schema;
      

      Copy

2. Create custom role account_budget_admin for the account budget administrator. The account budget administrator 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.

   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

3. Create custom role account_budget_monitor to be granted to account budget monitors. An account budget monitor can take the following actions on the account budget:

   • Monitor credit usage for the account.

   • View the email notification settings.

   • View the monthly spending limit for the account.

   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

4. Create a custom role budget_owner with the required role and privileges to create custom budgets in the schema budgets_db.budgets_schema:

   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

5. Create two custom roles to manage and monitor custom budgets. These roles will be granted additional privileges later in the tutorial after the custom budget is created. To create the custom roles, follow these steps:

   1. Create a custom budget_admin role that can manage and monitor a custom budget:

      USE ROLE ACCOUNTADMIN;
      
      CREATE ROLE budget_admin;
      
      GRANT USAGE ON DATABASE budgets_db TO ROLE budget_admin;
      
      GRANT USAGE ON SCHEMA budgets_db.budgets_schema TO ROLE budget_admin;
      
      GRANT DATABASE ROLE SNOWFLAKE.USAGE_VIEWER TO ROLE budget_admin;
      

      Copy

   1. Create a custom budget_monitor role that can monitor a custom budget:

   USE ROLE ACCOUNTADMIN;
   
   CREATE ROLE budget_monitor;
   
   GRANT USAGE ON DATABASE budgets_db TO ROLE budget_monitor;
   
   GRANT USAGE ON SCHEMA budgets_db.budgets_schema TO ROLE budget_monitor;
   
   GRANT DATABASE ROLE SNOWFLAKE.USAGE_VIEWER TO ROLE budget_monitor;
   

   Copy

6. Grant custom budget roles to yourself to use in future steps of the tutorial:

   SQLSnowsight

   1. Grant the account_budget_admin role to yourself:

      GRANT ROLE account_budget_admin
        TO USER <YOUR_USER_NAME>;
      

      Copy

   2. Grant the account_budget_monitor role to yourself:

      GRANT ROLE account_budget_monitor
        TO USER <YOUR_USER_NAME>;
      

      Copy

   3. Grant the budget_owner role to yourself:

      GRANT ROLE budget_owner
        TO USER <YOUR_USER_NAME>;
      

      Copy

   4. Grant the budget_monitor role to yourself:

      GRANT ROLE budget_monitor
        TO USER <YOUR_USER_NAME>;
      

      Copy

In this section, you created custom roles to manage and monitor budgets, and create custom budgets.

Create the objects for the custom budget¶

In this step, create objects to add to a custom budget and grant privileges to the custom roles you created in the previous step. You will be creating the following objects:

• A warehouse to add to a custom budget.

• A database to add to a custom budget.

1. Create a warehouse and grant the USAGE and APPLYBUDGET privileges on the warehouse to the custom roles you created. The APPLYBUDGET privilege is required to add an object to a budget.

   SQLSnowsight

   1. Create warehouse na_finance_wh:

      CREATE WAREHOUSE na_finance_wh;
      

      Copy

   2. Grant the USAGE privilege to custom budget roles:

      GRANT USAGE ON WAREHOUSE na_finance_wh TO ROLE account_budget_admin;
      GRANT USAGE ON WAREHOUSE na_finance_wh TO ROLE account_budget_monitor;
      GRANT USAGE ON WAREHOUSE na_finance_wh TO ROLE budget_admin;
      GRANT USAGE ON WAREHOUSE na_finance_wh TO ROLE budget_owner;
      GRANT USAGE ON WAREHOUSE na_finance_wh TO ROLE budget_monitor;
      

      Copy

   3. Grant the APPLYBUDGET privilege on the warehouse to role budget_owner:

      GRANT APPLYBUDGET ON WAREHOUSE na_finance_wh TO ROLE budget_owner;
      

      Copy

2. Create a database and grant the APPLYBUDGET privilege on the warehouse to the custom budget owner role you created. The APPLYBUDGET privilege is required to add an object to a budget.

   SQLSnowsight

   1. Create a database:

      CREATE DATABASE na_finance_db;
      

      Copy

   2. Grant the APPLYBUDGET privilege on the database to role budget_owner:

      GRANT APPLYBUDGET ON DATABASE  na_finance_db TO ROLE budget_owner;
      

      Copy

In this section, you created the objects to be added to a custom budget and granted the APPLYBUDGET privilege required to add those objects to a budget. You also created the database and schema in which to create the custom budget and granted the USAGE privilege required to create a budget in the schema. Now you are ready to activate, create, and set up budgets.

Activate and set up the account budget¶

The account budget monitors credit usage for the compute costs of all Budgets supported objects in the account, including background maintenance tasks (for example, automatic clustering) and serverless features. The account budget must be activated before it can start monitoring credit usage. After it is activated, you can set the monthly spending limit for the account and the email list of notification recipients. Budgets sends a notification email when current credit usage is expected to exceed the monthly spending limit.

Activate and set up the account budget using the following steps:

In this section, you activated the account budget and set the spending limit and the email address to receive budget notifications.

Create a custom budget¶

Now that you have activated and set up your account budget, create a custom budget to monitor the credit usage in your account for a specified group of objects. For this tutorial, add the na_finance_wh warehouse and na_finance_db to the custom budget.

Create custom budgets with the following steps:

1. Use the budget_owner role to create budget na_finance_budget in budgets_db.budgets_schema:

   USE ROLE budget_owner;
   USE SCHEMA budgets_db.budgets_schema;
   USE WAREHOUSE na_finance_wh;
   
   CREATE SNOWFLAKE.CORE.BUDGET na_finance_budget();
   

   Copy

2. Set the monthly spending limit and email notification list for budget na_finance_budget using the following steps:

   SQLSnowsight

   1. Set the monthly spending limit to 500 credits:

      CALL na_finance_budget!SET_SPENDING_LIMIT(500);
      

      Copy

   2. To set up the notification list, use your verified email address and the notification integration created in the first step of the tutorial:

      CALL na_finance_budget!SET_EMAIL_NOTIFICATIONS('budgets_notification_integration',
                                                     '<YOUR_EMAIL_ADDRESS>');
      

      Copy

   3. Add database na_finance_db and warehouse na_finance_wh to budget na_finance_budget:

      CALL na_finance_budget!ADD_RESOURCE(
        SYSTEM$REFERENCE('database', 'na_finance_db', 'SESSION', 'applybudget'));
      
      CALL na_finance_budget!ADD_RESOURCE(
        SYSTEM$REFERENCE('warehouse', 'na_finance_wh', 'SESSION', 'applybudget'));
      

      Copy

3. Grant instance roles to the custom roles you created in a previous step.

   1. Grant the required roles and privileges to the budget_admin role to let the budget_admin role modify and monitor the custom budget na_finance_budget:

      USE ROLE budget_owner;
      
      GRANT SNOWFLAKE.CORE.BUDGET ROLE budgets_db.budgets_schema.na_finance_budget!ADMIN
        TO ROLE budget_admin;
      

      Copy

   2. Grant the VIEWER instance role to the budget_monitor role to let the budget_monitor role monitor the custom budget na_finance_budget:

      USE ROLE budget_owner;
      
      GRANT SNOWFLAKE.CORE.BUDGET ROLE budgets_db.budgets_schema.na_finance_budget!VIEWER
        TO ROLE budget_monitor;
      

      Copy

In this section, you created a custom budget, added objects for the budget to monitor, and set up the email address to receive budget notifications.

Monitoring credit usage¶

You have completed all the steps in the tutorial to activate your account budget, create a custom budget, and create custom roles to monitor and manage both account and custom budgets. Credit usage data for your budgets takes some time to populate.

Budgets uses serverless tasks to collect credit usage data for the budgets in your account. After you activate the account budget or create a custom budget, it takes a while for the serverless task to execute. After credit usage data becomes available, you can monitor credit usage for budgets using Snowsight.

To monitor credit usage after usage data becomes available, use the following steps:

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()
);

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()
);

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()
);

Clean up, summary, and additional resources¶

Congratulations! You have successfully completed this tutorial.

After credit usage data is populated for your account budget and custom budget, see Use Snowsight to monitor budgets.

USE ROLE budget_owner;

DROP SNOWFLAKE.CORE.BUDGET budgets_db.budgets_schema.na_finance_budget;

USE ROLE ACCOUNTADMIN;

DROP DATABASE na_finance_db;
DROP WAREHOUSE na_finance_wh;
DROP DATABASE budgets_db;

USE ROLE ACCOUNTADMIN;

DROP ROLE budget_monitor;
DROP ROLE budget_admin;
DROP ROLE budget_owner;

USE ROLE ACCOUNTADMIN;

DROP ROLE account_budget_monitor;
DROP ROLE account_budget_admin;

USE ROLE ACCOUNTADMIN;

DROP NOTIFICATION INTEGRATION budgets_notification_integration;