Manage workload assignments

The BigQuery Reservation API lets you purchase dedicated slots (calledcommitments), create poolsof slots (calledreservations),and assign projects, folders, and organizations to those reservations.

Create reservation assignments

To use the slots that you purchase, you create anassignment which assigns aproject, folder, or organization to a slot reservation. You can't assign orallocate a specific number of slots at the assignment level; slots are managedand assigned at the reservation level.

Projects use the single most specific reservation in the resource hierarchy towhich they are assigned. A folder assignment overrides an organizationassignment, and a project assignment overrides a folder assignment. Folder andorganization assignments are not available tostandardedition reservations.

In order to create an assignment on a reservation, the reservation must fulfillat least one of the following criteria:

  • It is configured with a non-zero amount of assigned baseline slots.

  • It is configured with a non-zero amount of autoscaling slots.

  • It is configured to use idle slots, and there are available idle slots withinthe project.

If you attempt to assign a resource to a reservation that doesn't meet at leastone of these criteria, you receive the followingmessage:Assignment is pending, your project will be executed as on-demand.

You can assign a resource to afailoverreservation, but the assignment pendsin the secondary location.

Required permissions

To create a reservation assignment, you need the followingIdentity and Access Management (IAM) permission:

Each of the following predefined IAM roles includes thispermission:

  • BigQuery Admin
  • BigQuery Resource Admin
  • BigQuery Resource Editor

For more information about IAM roles in BigQuery,seePredefined roles and permissions.

Assign an organization to a reservation

Console

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In the navigation menu, clickCapacity management.

  3. Click theReservations tab.

  4. Find the reservation in the table of reservations.

  5. Expand theActions option.

  6. ClickCreate assignment.

  7. In theCreate an assignment section, clickBrowse.

  8. Browse or search for the organization and select it.

  9. In theJob Type section, select a job type to assign forthis reservation. Options include the following:

    • QUERY
    • CONTINUOUS
    • PIPELINE
    • BACKGROUND
    • ML_EXTERNAL

    For more information about job types, seeReservation assignments.This default value isQUERY.

    To learn more about allowing users to useGemini in BigQuery with Enterprise Plus editionassignments, seeSetup Gemini in BigQuery.

  10. ClickCreate.

SQL

To assign an organization to a reservation, use theCREATE ASSIGNMENT DDL statement.

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In the query editor, enter the following statement:

    CREATEASSIGNMENT`ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME.ASSIGNMENT_ID`OPTIONS(assignee='organizations/ORGANIZATION_ID',job_type='JOB_TYPE');

    Replace the following:

    • ADMIN_PROJECT_ID: the project ID of theadministration project that owns the reservation resource
    • LOCATION: thelocation of the reservation
    • RESERVATION_NAME: the name of the reservation

    • ASSIGNMENT_ID: the ID of the assignment

      The ID must be unique to the project and location, start and end with a lowercase letter or a number, and contain only lowercase letters, numbers, and dashes.

    • ORGANIZATION_ID: theorganization ID
    • JOB_TYPE: thetype of job to assign to this reservation, such asQUERY,CONTINUOUS,PIPELINE,BACKGROUND, orML_EXTERNAL

  3. ClickRun.

For more information about how to run queries, seeRun an interactive query.

bq

To assign an organization's jobs to a reservation, use thebq mk commandwith the--reservation_assignment flag:

bq mk \    --project_id=ADMIN_PROJECT_ID \    --location=LOCATION \    --reservation_assignment \    --reservation_id=RESERVATION_NAME \    --assignee_id=ORGANIZATION_ID \    --job_type=JOB_TYPE \    --assignee_type=ORGANIZATION

Replace the following:

  • ADMIN_PROJECT_ID: the project ID of theadministration projectthat owns the reservation resource
  • LOCATION: thelocation of the reservation
  • RESERVATION_NAME: the name of thereservation
  • ORGANIZATION_ID: theorganization ID
  • JOB_TYPE: thetype of jobto assign to this reservation, such asQUERY,CONTINUOUS,PIPELINE,BACKGROUND, orML_EXTERNAL

When you create a reservation assignment, wait at least 5 minutes before runninga query. Otherwise the query might be billed using on-demand pricing.

Assign a project or folder to a reservation

Console

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In the navigation menu, clickCapacity management.

  3. Click theReservations tab.

  4. Find the reservation in the table of reservations.

  5. Expand theActions option.

  6. ClickCreate assignment.

  7. In theCreate an assignment section, clickBrowse.

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

  9. In theJob Type section, select a job type to assign forthis reservation. Options include the following:

    • QUERY
    • CONTINUOUS
    • PIPELINE
    • BACKGROUND
    • ML_EXTERNAL

    Creation and modification of more granular background job types such asBACKGROUND_COLUMN_METADATA_INDEX are not yet supported through the console.

    For more information about job types, seereservation assignments.This default value isQUERY.

  10. ClickCreate.

SQL

To assign a project to a reservation, use theCREATE ASSIGNMENT DDL statement.

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In the query editor, enter the following statement:

    CREATEASSIGNMENT`ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME.ASSIGNMENT_ID`OPTIONS(assignee="projects/PROJECT_ID",job_type="JOB_TYPE");

    Replace the following:

    • ADMIN_PROJECT_ID: the project ID of theadministration project that owns the reservation resource
    • LOCATION: thelocation of the reservation
    • RESERVATION_NAME: the name of the reservation

    • ASSIGNMENT_ID: the ID of the assignment

      The ID must be unique to the project and location, start and end with a lowercase letter or a number, and contain only lowercase letters, numbers, and dashes.

    • PROJECT_ID: the ID of the project to assign to the reservation
    • JOB_TYPE: thetype of job to assign to this reservation, such asQUERY,CONTINUOUS,PIPELINE,BACKGROUND_CHANGE_DATA_CAPTURE,BACKGROUND_COLUMN_METADATA_INDEX,BACKGROUND_SEARCH_INDEX_REFRESH,BACKGROUND, orML_EXTERNAL

  3. ClickRun.

For more information about how to run queries, seeRun an interactive query.

bq

To assign jobs to a reservation, use thebq mk command with the--reservation_assignment flag:

bq mk \    --project_id=ADMIN_PROJECT_ID \    --location=LOCATION \    --reservation_assignment \    --reservation_id=RESERVATION_NAME \    --assignee_id=PROJECT_ID \    --job_type=JOB_TYPE \    --assignee_type=PROJECT

Replace the following:

  • ADMIN_PROJECT_ID: the project ID of theadministration projectthat owns the reservation resource
  • LOCATION: thelocation of the reservation
  • RESERVATION_NAME: the name of thereservation
  • PROJECT_ID: the ID of the project to assignto this reservation
  • JOB_TYPE: thetype of jobto assign to this reservation, such asQUERY,CONTINUOUS,PIPELINE,BACKGROUND_CHANGE_DATA_CAPTURE,BACKGROUND_COLUMN_METADATA_INDEX,BACKGROUND_SEARCH_INDEX_REFRESH,BACKGROUND, orML_EXTERNAL

Terraform

Use thegoogle_bigquery_reservation_assignmentresource.

Note: To create BigQuery objects using Terraform, you mustenable theCloud Resource Manager API.

To authenticate to BigQuery, set up Application DefaultCredentials. For more information, seeSet up authentication for client libraries.

The following example assigns a project to the reservation namedmy-reservation:

resource "google_bigquery_reservation" "default" {  name              = "my-reservation"  location          = "us-central1"  slot_capacity     = 100  edition           = "ENTERPRISE"  ignore_idle_slots = false # Use idle slots from other reservations  concurrency       = 0     # Automatically adjust query concurrency based on available resources  autoscale {    max_slots = 200 # Allow the reservation to scale up to 300 slots (slot_capacity + max_slots) if needed  }}data "google_project" "project" {}resource "google_bigquery_reservation_assignment" "default" {  assignee    = "projects/${data.google_project.project.project_id}"  job_type    = "QUERY"  reservation = google_bigquery_reservation.default.id}

To apply your Terraform configuration in a Google Cloud project, complete the steps in the following sections.

Prepare Cloud Shell

  1. LaunchCloud Shell.

  2. Set the default Google Cloud project where you want to apply your Terraform configurations.

    You only need to run this command once per project, and you can run it in any directory.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Environment variables are overridden if you set explicit values in the Terraform configuration file.

Prepare the directory

Each Terraform configuration file must have its own directory (alsocalled aroot module).

  1. InCloud Shell, create a directory and a new file within that directory. The filename must have the.tf extension—for examplemain.tf. In this tutorial, the file is referred to asmain.tf.
    mkdirDIRECTORY && cdDIRECTORY && touch main.tf

  2. If you are following a tutorial, you can copy the sample code in each section or step.

    Copy the sample code into the newly createdmain.tf.

    Optionally, copy the code from GitHub. This is recommended when the Terraform snippet is part of an end-to-end solution.

  3. Review and modify the sample parameters to apply to your environment.
  4. Save your changes.
  5. Initialize Terraform. You only need to do this once per directory.
    terraform init

    Optionally, to use the latest Google provider version, include the-upgrade option:

    terraform init -upgrade

Apply the changes

  1. Review the configuration and verify that the resources that Terraform is going to create or update match your expectations:
    terraform plan

    Make corrections to the configuration as necessary.

  2. Apply the Terraform configuration by running the following command and enteringyes at the prompt:
    terraform apply

    Wait until Terraform displays the "Apply complete!" message.

  3. Open your Google Cloud project to view the results. In the Google Cloud console, navigate to your resources in the UI to make sure that Terraform has created or updated them.
Note: Terraform samples typically assume that the required APIs are enabled in your Google Cloud project.

When you create a reservation assignment, wait at least 5 minutes before runninga query. Otherwise the query might be billed using on-demand pricing.

To make a project that only usesidleslots,create areservation with0slots assigned to it, then follow the prior steps to assign the project to thatreservation.

Note: A project can be assigned to at most one reservation in a single region.

Assign a project tonone

Assignments tonone represent the absence of an assignment. Projects assignedtonone use on-demand pricing.

Note: Assignments tonone are supported for QUERY jobs only.

SQL

To assign a project tonone, use theCREATE ASSIGNMENT DDL statement.

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In the query editor, enter the following statement:

    CREATEASSIGNMENT`ADMIN_PROJECT_ID.region-LOCATION.none.ASSIGNMENT_ID`OPTIONS(assignee="projects/PROJECT_ID",job_type="QUERY");

    Replace the following:

    • LOCATION: thelocation of jobs that should use on-demand pricing

    • ASSIGNMENT_ID: the ID of the assignment

      The ID must be unique to the project and location, start and end with a lowercase letter or a number, and contain only lowercase letters, numbers, and dashes.

    • PROJECT_ID: the ID of the project to assign to the reservation

  3. ClickRun.

For more information about how to run queries, seeRun an interactive query.

bq

To assign a project tonone, use thebq mk command with the--reservation_assignment flag:

bq mk \    --location=LOCATION \    --reservation_assignment \    --reservation_id=none \    --job_type=QUERY \    --assignee_id=PROJECT_ID \    --assignee_type=PROJECT

Replace the following:

  • LOCATION: thelocationof jobs that should use on-demand pricing
  • PROJECT_ID: the ID of the project to assigntonone

Terraform

Use thegoogle_bigquery_reservation_assignmentresource.

Note: To create BigQuery objects using Terraform, you mustenable theCloud Resource Manager API.

To authenticate to BigQuery, set up Application DefaultCredentials. For more information, seeSet up authentication for client libraries.

The following example assigns a project tonone:

data "google_project" "project" {}resource "google_bigquery_reservation_assignment" "default" {  assignee    = "projects/${data.google_project.project.project_id}"  job_type    = "QUERY"  reservation = "projects/${data.google_project.project.project_id}/locations/us/reservations/none"}

To apply your Terraform configuration in a Google Cloud project, complete the steps in the following sections.

Prepare Cloud Shell

  1. LaunchCloud Shell.

  2. Set the default Google Cloud project where you want to apply your Terraform configurations.

    You only need to run this command once per project, and you can run it in any directory.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Environment variables are overridden if you set explicit values in the Terraform configuration file.

Prepare the directory

Each Terraform configuration file must have its own directory (alsocalled aroot module).

  1. InCloud Shell, create a directory and a new file within that directory. The filename must have the.tf extension—for examplemain.tf. In this tutorial, the file is referred to asmain.tf.
    mkdirDIRECTORY && cdDIRECTORY && touch main.tf

  2. If you are following a tutorial, you can copy the sample code in each section or step.

    Copy the sample code into the newly createdmain.tf.

    Optionally, copy the code from GitHub. This is recommended when the Terraform snippet is part of an end-to-end solution.

  3. Review and modify the sample parameters to apply to your environment.
  4. Save your changes.
  5. Initialize Terraform. You only need to do this once per directory.
    terraform init

    Optionally, to use the latest Google provider version, include the-upgrade option:

    terraform init -upgrade

Apply the changes

  1. Review the configuration and verify that the resources that Terraform is going to create or update match your expectations:
    terraform plan

    Make corrections to the configuration as necessary.

  2. Apply the Terraform configuration by running the following command and enteringyes at the prompt:
    terraform apply

    Wait until Terraform displays the "Apply complete!" message.

  3. Open your Google Cloud project to view the results. In the Google Cloud console, navigate to your resources in the UI to make sure that Terraform has created or updated them.
Note: Terraform samples typically assume that the required APIs are enabled in your Google Cloud project.

Override a reservation on a query

To use a specific reservation in a query, you need the followingIdentity and Access Management (IAM) permission:

To assign a query to run in a specific reservation, do one of the following:

Console

  1. Go to theBigQuery page.

    Go to BigQuery

  2. ClickSQL query.

  3. In the query editor, enter a valid GoogleSQL query.

  4. ClickMore, and thenclickQuery settings.

  5. Clear theAutomatic location setting checkbox, and then select theregion or multi-region the reservation is in.

  6. In theReservation list, select the reservation you want the queryto run in.

  7. ClickSave.

  8. Write a query in the editor tab and runit. The query runs in the reservationyou specified.

SQL

You can use the@@reservation system variable to assign thereservation your query runs in:

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In the query editor, enter the following statement:

    SET@@reservation='RESERVATION';SELECTQUERY;

    Replace the following:

    • RESERVATION: the reservation you want thequery to run in.

    • QUERY: the query you want to run.

  3. ClickRun.

For more information about how to run queries, seeRun an interactive query.

For example, the following query uses theSETstatement to set the reservation to thetest-reservation in theUSmulti-region, then calls a basic query:

SET@@reservation='projects/project1/locations/US/reservations/test-reservation';SELECT42;

bq

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, aCloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. In Cloud Shell, run the query by using thebq query commandwith the--reservation_id flag:

    bqquery--use_legacy_sql=false--reservation_id=RESERVATION_ID'QUERY'

    Replace the following:

    • RESERVATION_ID: the reservation youwant to run the query in.

    • QUERY: the SQL statement for the query.

    For example, the following query runs in thetest-reservationreservation in theUS multi-region:

    bqquery--reservation_id=project1.US:test-reservation'SELECT 42;'

API

To specify a reservation using the API,insert a newjob and populate thequeryjob configuration property. Specify your reservation in thereservationfield.

Caution: A query can use a reservation declared in another project.However, the query and the reservation must be in the same organization and in the same location.

Assign slots to BigQuery ML workloads

The following sections provide information on reservationassignment requirements for BigQuery ML models.You can create these reservation assignments by following the procedures inAssign an organization to a reservationorAssign a project or folder to a reservation.

External models

The following BigQuery ML model types use external services:

You can assign reserved slots to queries using these services by creating areservation assignment that uses theML_EXTERNAL job type. If noreservation assignment with anML_EXTERNALjob type is found, the query jobruns usingon-demand pricing.

For external model training jobs, the slots in the reservation assignment areused for preprocessing, training, and postprocessing steps. During training,the slots aren't preemptible, but during preprocessing and postprocessing,idle slots can be used.

Matrix factorization models

To create a matrix factorization model you mustcreate a reservationthat uses the BigQueryEnterprise or Enterprise Plus edition,and then create a reservation assignment that uses theQUERY job type.

Other model types

For BigQuery ML models that aren't external models or matrixfactorization models, you can assign reserved slots to queries using theseservices by creating a reservation assignment that uses theQUERY job type.If no reservation assignment with aQUERY job type is found, the query jobruns usingon-demand pricing.

Find reservation assignments

Required permissions

To search for a reservation assignment for a given project, folder, ororganization, you need the following Identity and Access Management (IAM) permission:

  • bigquery.reservationAssignments.list on the administration project.

Each of the following predefined IAM roles includes thispermission:

  • BigQuery Admin
  • BigQuery Resource Admin
  • BigQuery Resource Editor
  • BigQuery Resource Viewer
  • BigQuery User

For more information about IAM roles in BigQuery,seePredefined roles and permissions.

Find a project's reservation assignment

You can find out if your project, folder, or organization is assigned to areservation by doing the following:

Console

  1. In the Google Cloud console, go to the BigQuery page.

    Go to BigQuery

  2. In the navigation menu, clickCapacity management.

  3. Click theReservations tab.

  4. In the table of reservations, expand a reservation to see what resourcesare assigned to that reservation, or use theFilter field to filterby resource name.

SQL

To find which reservation your project's query jobs are assigned to, querytheINFORMATION_SCHEMA.ASSIGNMENTS_BY_PROJECT view.

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In the query editor, enter the following statement:

    SELECTassignment_idFROM`region-LOCATION`.INFORMATION_SCHEMA.ASSIGNMENTS_BY_PROJECTWHEREassignee_id='PROJECT_ID'ANDjob_type='JOB_TYPE';

    Replace the following:

    • LOCATION: thelocation of reservations to view
    • ADMIN_PROJECT_ID: the project ID of theadministration project that owns the reservation resource
    • PROJECT_ID: the ID of the project to assign to the reservation
    • JOB_TYPE: thetype of job to assign to this reservation, such asQUERY,CONTINUOUS,PIPELINE,BACKGROUND, orML_EXTERNAL

  3. ClickRun.

For more information about how to run queries, seeRun an interactive query.

bq

Caution: This command does not work in Cloud Shell. To use this command,run it from a local command line.

To find which reservation your project's query jobs are assigned to, use thebq show command with the--reservation_assignment flag:

bq show \    --project_id=ADMIN_PROJECT_ID \    --location=LOCATION \    --reservation_assignment \    --job_type=JOB_TYPE \    --assignee_id=PROJECT_ID \    --assignee_type=PROJECT

Replace the following:

Update reservation assignments

Move an assignment to a different reservation

You can move an assignment from one reservation to another reservation.

To move a reservation assignment, you need the followingIdentity and Access Management (IAM) permissions on theadministration projectand the assignee.

  • bigquery.reservationAssignments.create
  • bigquery.reservationAssignments.delete

Each of the following predefined IAM roles includes thesepermissions:

  • BigQuery Admin
  • BigQuery Resource Admin
  • BigQuery Resource Editor

For more information about IAM roles in BigQuery,seePredefined roles and permissions.

To move an assignment, use thebq update command:

bq update \    --project_id=ADMIN_PROJECT_ID \    --location=LOCATION \    --reservation_assignment \    --destination_reservation_id=DESTINATION_RESERVATION \ADMIN_PROJECT_ID:LOCATION.RESERVATION_NAME.ASSIGNMENT_ID

Replace the following:

  • ADMIN_PROJECT_ID: the ID of the project thatowns the reservation resource
  • LOCATION: thelocationof the new reservation
  • RESERVATION_NAME: the reservation to move theassignment from
  • DESTINATION_RESERVATION: thereservation to move the assignment to

  • ASSIGNMENT_ID: the ID of the assignment

    To get the assignment ID, seeList a project's reservation assignment.

Note: Updated reservation assignments only apply to new jobs. Existing jobs continue to use their original reservation assignment.

Delete reservation assignments

You can remove a project from a reservation by deleting the reservationassignment. If a project is not assigned to any reservations, it inherits anyassignments in its parent folders or organizations, or else uses on-demandpricing if there are no parent assignments.

When you delete a reservation assignment, the jobs executing with slots fromthat reservation continue to run until completion.

Required permissions

To delete a reservation assignment, you need the followingIdentity and Access Management (IAM) permission:

Each of the following predefined IAM roles includes thispermission:

  • BigQuery Admin
  • BigQuery Resource Admin
  • BigQuery Resource Editor

Remove a project from a reservation

To remove a project from a reservation:

Console

  1. In the Google Cloud console, go to the BigQuery page.

    Go to BigQuery

  2. In the navigation menu, clickCapacity management.

  3. Click theReservations tab.

  4. In the table of reservations, expand the reservation to find theproject.

  5. Expand theActions option.

  6. ClickDelete.

SQL

Use theDROP ASSIGNMENT DDL statement.

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In the query editor, enter the following statement:

    DROPASSIGNMENT`ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME.ASSIGNMENT_ID`;

    Replace the following:

  3. ClickRun.

For more information about how to run queries, seeRun an interactive query.

bq

To remove a project from a reservation, use thebq rm command with the--reservation_assignment flag:

bq rm \    --project_id=ADMIN_PROJECT_ID \    --location=LOCATION \    --reservation_assignmentRESERVATION_NAME.ASSIGNMENT_ID

Replace the following:

  • ADMIN_PROJECT_ID: the ID of the project thatowns the reservation resource
  • LOCATION: thelocationof the reservation
  • RESERVATION_NAME: the name of thereservation

  • ASSIGNMENT_ID: the ID of the assignment

    To get the assignment ID, seeFind a project's reservation assignment.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.