Getting started with Reservations

This tutorial shows how to get started with BigQuery Reservations. In this tutorial, you will:

  • Purchase Flex slots, which have a minimum 60-second commitment. The tutorial uses Flex slots because you can cancel them after 60 seconds, but you would follow the same steps to purchase a monthly or annual commitment. For more information, see Commitment plans.
  • Create a reservation and allocate slots to it.
  • Assign a project to the reservation.

Before starting this tutorial, consider reading Introduction to Reservations to understand the basic concepts.

Costs

In this tutorial, you will purchase Flex slots. For pricing information, see Flat-rate pricing. You can cancel the slots after 60 seconds, but you are charged until you cancel them. To avoid being charged after you complete the tutorial, make sure to follow the steps in Cleaning up.

Before you begin

Create a Google Cloud project to administer the reservation as follows. Give it a descriptive name like bq-COMPANY_NAME-admin.

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
  2. In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.

Enable the Reservations API in the administration project. For more information, see Enabling the Reservations API.

Purchase slots

Use the Cloud Console or the bq command-line tool to purchase 100 Flex slots in the US multi-region.

Console

  1. In the Cloud Console, go to the BigQuery page.

    Go to BigQuery

  2. In the navigation panel, go to the Reservations section.

    Reservations navigation button.

  3. Click Buy slots.

  4. In the Buy Slots dialog:

    1. Select Flex for the commitment duration.
    2. Select United States for the location.
    3. Enter 100 for the number of slots.
    4. Click Next.

    Select Flex.

  5. Review your order and confirm it by typing CONFIRM. Click Purchase to purchase the slots.

  6. Click View slot commitments to view the status of the commitment. After the capacity is provisioned, the status shows a green check mark.

    Slot commitments.

bq

  1. Use the bq mk command with the --capacity_commitment flag to purchase 100 Flex slots.

    bq mk \
     --project_id=ADMIN_PROJECT_ID \
     --location=US \
     --capacity_commitment \
     --plan=FLEX \
     --slots=100
    

    Replace ADMIN_PROJECT_ID with the project ID of the administration project.

    The output shows the ID of the commitment. You will need this ID later when you delete the commitment. The cleanup steps show how to list the ID again.

Create a reservation

Create a reservation named prod in the US multi-region and allocate 100 slots to it.

Console

  1. In the Cloud Console, click Create reservation.
  2. In the Reservation name field, enter prod.
  3. In the Location drop-down list, select United States.
  4. In the Allocate slots field, enter 100.
  5. Click Save.

    Create a reservation.

bq

  1. Use the bq mk command with the --reservation flag to create a reservation named prod with 100 slots.

    bq mk \
     --project_id=ADMIN_PROJECT_ID \
     --location=US \
     --reservation \
     --slots=100 \
     prod
    

    Replace ADMIN_PROJECT_ID with the project ID of the administration project.

Assign a project to a reservation

Assign a project to the prod reservation. Any query jobs that run from this project will use the pool of slots from the prod reservation. (You don't run a job in this tutorial, however.)

You can assign any project that's in the same organization and region as the administration project where you created the commitment.

Console

  1. In the Cloud Console, click the Reservations tab.
  2. Find the reservation named prod.
  3. Expand the Actions option.

    Assignments project picker.

  4. Click Create assignment.

  5. In the Create an assignment section, click Browse.

  6. Browse or search for the project or folder and select it.

  7. Click Create.

bq

  1. Use the bq mk command with the --reservation_assignment flag to assign a project to the prod reservation.

    bq mk \
     --project_id=ADMIN_PROJECT_ID \
     --location=US \
     --reservation_assignment \
     --reservation_id=ADMIN_PROJECT_ID:US.prod \
     --job_type=QUERY \
     --assignee_id=MY_PROD_PROJECT \
     --assignee_type=PROJECT
    

    Replace the following:

    • ADMIN_PROJECT_ID: the project ID of the administration project.

    • MY_PROD_PROJECT: the project ID of the project to assign to the reservation.

    The output shows the ID of the assignment. You will need this ID later when you remove the assignment. The cleanup steps show how to list the ID again.

Cleaning up

To avoid being charged after you finish this tutorial, delete the Flex commitment as follows:

Remove the assignment

Console

  1. Click the Reservations tab.
  2. Locate the reservation named prod and expand the Actions option.
  3. Click Delete.

bq

  1. Use the bq show command to get the assignment ID.

    bq show \
     --project_id=ADMIN_PROJECT_ID \
     --location=US \
     --reservation_assignment \
     --job_type=QUERY \
     --assignee_id=MY_PROD_PROJECT \
     --assignee_type=PROJECT
    

    Replace the following:

    • ADMIN_PROJECT_ID: the project ID of the administration project.

    The ID will look similar to the following:

    myproject:US.prod.1234567891011121314
    
  2. Use the bq rm command with the --reservation_assignment flag to remove the assignment.

    bq rm \
      --project_id=ADMIN_PROJECT_ID \
      --location=US \
      --reservation_assignment \
      RESERVATION_ASSIGNMENT_ID
    

    Replace the following:

    • ADMIN_PROJECT_ID: the project ID of the administration project.
    • RESERVATION_ASSIGNMENT_ID: the reservation assignment ID from the previous step.

Delete the reservation

When you delete a reservation, any jobs that are currently executing with slots from that reservation will fail. To prevent errors, allow in-flight jobs to complete before deleting the reservation.

Console

  1. In the Cloud Console, click the Reservations tab.
  2. Locate the prod reservation and expand the Actions option.
  3. Click Delete.

bq

  1. Use the bq rm command with the --reservation flag to delete the reservation.

    bq rm \
      --project_id=ADMIN_PROJECT_ID \
      --location=US \
      --reservation \
      prod
    

    Replace the following:

    • ADMIN_PROJECT_ID: the project ID of the administration project.

Delete the commitment

Console

  1. In the Cloud Console, click the Slot commitments tab.

  2. Locate the flex commitment that you purchased and expand the Actions option.

  3. Click Delete.

  4. In the dialog, type REMOVE and click Proceed.

bq

  1. Use the bq show command to get the ID of the capacity commitment.

    bq ls \
     --capacity_commitment \
     --location=US \
     --project_id=ADMIN_PROJECT_ID
    

    Replace the following:

    • ADMIN_PROJECT_ID: the project ID of the administration project.

    The ID will look similar to the following:

    myproject:US.1234567891011121314
    
  2. Use the bq rm command with the --capacity_commitment flag to delete the commitment.

    bq rm \
     --project_id=ADMIN_PROJECT_ID \
     --location=US \
     --capacity_commitment \
     COMMITMENT_ID
    

    Replace the following:

    • ADMIN_PROJECT_ID: the project ID of the administration project.
    • COMMITMENT_ID: the capacity commitment ID from the previous step.

What's next