Package google.cloud.bigquery.reservation.v1beta1

Index

ReservationService

This API allows users to manage their flat-rate BigQuery reservations.

A reservation provides computational resource guarantees, in the form of slots, to users. A slot is a unit of computational power in BigQuery, and serves as the basic unit of parallelism. In a scan of a multi-partitioned table, a single slot operates on a single partition of the table. A reservation resource exists as a child resource of the admin project and location, e.g.: projects/myproject/locations/US/reservations/reservationName.

A capacity commitment is a way to purchase compute capacity for BigQuery jobs (in the form of slots) with some committed period of usage. A capacity commitment resource exists as a child resource of the admin project and location, e.g.: projects/myproject/locations/US/capacityCommitments/id.

CreateAssignment

rpc CreateAssignment(CreateAssignmentRequest) returns (Assignment)

Returns google.rpc.Code.PERMISSION_DENIED if user does not have 'bigquery.admin' permissions on the project using the reservation and the project that owns this reservation. Returns google.rpc.Code.INVALID_ARGUMENT when location of the assignment does not match location of the reservation.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/bigquery
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
CreateReservation

rpc CreateReservation(CreateReservationRequest) returns (Reservation)

Creates a new reservation resource.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/bigquery
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
DeleteAssignment

rpc DeleteAssignment(DeleteAssignmentRequest) returns (Empty)

Deletes a assignment. No expansion will happen. E.g: organizationA contains project1 and project2. Reservation res1 exists. CreateAssignment was invoked previously and following assignments were created explicitly: <organizationA, res1> <project1, res1> Then deletion of <organizationA, res1> won't affect <project1, res1>. After deletion of <organizationA, res1>, queries from project1 will still use res1, while queries from project2 will use on-demand mode.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/bigquery
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
DeleteCapacityCommitment

rpc DeleteCapacityCommitment(DeleteCapacityCommitmentRequest) returns (Empty)

Deletes a capacity commitment. Attempting to delete capacity commitment before its commitment_end_time will fail with the error code google.rpc.Code.FAILED_PRECONDITION.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/bigquery
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
DeleteReservation

rpc DeleteReservation(DeleteReservationRequest) returns (Empty)

Deletes a reservation. Returns google.rpc.Code.FAILED_PRECONDITION when reservation has assignments.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/bigquery
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
GetBiReservation

rpc GetBiReservation(GetBiReservationRequest) returns (BiReservation)

Retrieves a BI reservation.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/bigquery
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
GetCapacityCommitment

rpc GetCapacityCommitment(GetCapacityCommitmentRequest) returns (CapacityCommitment)

Returns information about the capacity commitment.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/bigquery
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
GetReservation

rpc GetReservation(GetReservationRequest) returns (Reservation)

Returns information about the reservation.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/bigquery
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
ListAssignments

rpc ListAssignments(ListAssignmentsRequest) returns (ListAssignmentsResponse)

Lists assignments. Only explicitly created assignments will be returned. E.g: organizationA contains project1 and project2. Reservation res1 exists. CreateAssignment was invoked previously and following assignments were created explicitly: <organizationA, res1> <project1, res1> Then this API will just return the above two assignments for reservation res1, and no expansion/merge will happen. Wildcard "-" can be used for reservations in the request. In that case all assignments belongs to the specified project and location will be listed. Note "-" cannot be used for projects nor locations.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/bigquery
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
ListCapacityCommitments

rpc ListCapacityCommitments(ListCapacityCommitmentsRequest) returns (ListCapacityCommitmentsResponse)

Lists all the capacity commitments for the admin project.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/bigquery
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
ListReservations

rpc ListReservations(ListReservationsRequest) returns (ListReservationsResponse)

Lists all the reservations for the project in the specified location.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/bigquery
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
MergeCapacityCommitments

rpc MergeCapacityCommitments(MergeCapacityCommitmentsRequest) returns (CapacityCommitment)

Merges capacity commitments of the same plan into one. Resulting capacity commitment has the longer commitment_end_time out of the two. Attempting to merge capacity commitments of different plan will fail with the error code google.rpc.Code.FAILED_PRECONDITION.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/bigquery
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
MoveAssignment

rpc MoveAssignment(MoveAssignmentRequest) returns (Assignment)

Moves a assignment under a new reservation. Customers can do this by deleting the existing assignment followed by creating another assignment under the new reservation, but this method provides a transactional way to do so, to make sure the assignee always has an associated reservation. Without the method customers might see some queries run on-demand which might be unexpected.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/bigquery
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
SearchAssignments

rpc SearchAssignments(SearchAssignmentsRequest) returns (SearchAssignmentsResponse)

Looks up assignments for a specified resource for a particular region. If the request is about a project: 1) Assignments created on the project will be returned if they exist. 2) Otherwise assignments created on the closest ancestor will be returned. 3) Assignments for different JobTypes will all be returned. Same logic applies if the request is about a folder. If the request is about an organization, then assignments created on the organization will be returned (organization doesn't have ancestors). Comparing to ListAssignments, there are some behavior differences: 1) permission on the assignee will be verified in this API. 2) Hierarchy lookup (project->folder->organization) happens in this API. 3) Parent here is projects/*/locations/*, instead of projects/*/locations/*reservations/*. Note "-" cannot be used for projects nor locations.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/bigquery
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
SplitCapacityCommitment

rpc SplitCapacityCommitment(SplitCapacityCommitmentRequest) returns (SplitCapacityCommitmentResponse)

Splits capacity commitment to two commitments of the same plan and commitment_end_time. A common use case to do that is to perform a downgrade e.g., in order to downgrade from 10000 slots to 8000, one might split 10000 capacity commitment to 2000 and 8000, change the plan of the first one to flex and then delete it.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/bigquery
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
UpdateBiReservation

rpc UpdateBiReservation(UpdateBiReservationRequest) returns (BiReservation)

Updates a BI reservation. Only fields specified in the field_mask are updated. Singleton BI reservation always exists with default size 0. In order to reserve BI capacity it needs to be updated to an amount greater than 0. In order to release BI capacity reservation size must be set to 0.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/bigquery
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
UpdateCapacityCommitment

rpc UpdateCapacityCommitment(UpdateCapacityCommitmentRequest) returns (CapacityCommitment)

Updates an existing capacity commitment.

Only plan and renewal_plan fields can be updated. Plan can only be changed to a plan of a longer commitment period. Attempting to change to a plan with shorter commitment period will fail with the error code google.rpc.Code.FAILED_PRECONDITION.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/bigquery
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
UpdateReservation

rpc UpdateReservation(UpdateReservationRequest) returns (Reservation)

Updates an existing reservation resource.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/bigquery
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

Assignment

A Assignment allows a project to submit jobs of a certain type using slots from the specified reservation.

Fields
name

string

Output only. Name of the resource. E.g.: projects/myproject/locations/US/reservations/team1-prod/assignments/123.
assignee

string

The resource which will use the reservation. E.g. projects/myproject, folders/123, organizations/456.
job_type

JobType

Which type of jobs will use the reservation.
state

State

Output only. State of the assignment.

JobType

Types of job, which could be specified when using the reservation.

Enums
JOB_TYPE_UNSPECIFIED Invalid type. Requests with this value will be rejected with error code google.rpc.Code.INVALID_ARGUMENT.
PIPELINE Pipeline (load/export) jobs from the project will use the reservation.
QUERY Query jobs from the project will use the reservation.

State

Assignment will remain in PENDING state if no active capacity commitment is present. It will become ACTIVE when some capacity commitment becomes active.

Enums
STATE_UNSPECIFIED Invalid state value.
PENDING Queries from assignee will be executed as on-demand, if related assignment is pending.
ACTIVE Assignment is ready.

BiReservation

Represents a BI Reservation.

Fields
name

string

The resource name of the singleton BI reservation. Reservation names have the form projects/{project_id}/locations/{location_id}/bireservation.
update_time

Timestamp

Output only. The last update timestamp of a reservation.
size

int64

Size of a reservation, in bytes.

CapacityCommitment

Capacity commitment is a way to purchase compute capacity for BigQuery jobs (in the form of slots) with some committed period of usage. Annual commitments renew by default. Commitments can be removed after their commitment end time passes. In order to remove annual commitment, its plan needs to be changed to monthly or flex first.

A capacity commitment resource exists as a child resource of the admin project.

Fields
name

string

Output only. The resource name of the capacity commitment, e.g., projects/myproject/locations/US/capacityCommitments/123
slot_count

int64

Number of slots in this commitment.
plan

CommitmentPlan

Capacity commitment commitment plan.
state

State

Output only. State of the commitment.
commitment_end_time

Timestamp

Output only. The end of the current commitment period. It is applicable only for ACTIVE capacity commitments.
failure_status

Status

Output only. For FAILED commitment plan, provides the reason of failure.
renewal_plan

CommitmentPlan

The plan this capacity commitment is converted to after commitment_end_time passes. Once the plan is changed, committed period is extended according to commitment plan. Only applicable for ANNUAL commitments.

CommitmentPlan

Commitment plan defines the current committed period. Capacity commitment cannot be deleted during it's committed period.

Enums
COMMITMENT_PLAN_UNSPECIFIED Invalid plan value. Requests with this value will be rejected with error code google.rpc.Code.INVALID_ARGUMENT.
FLEX Flex commitments have committed period of 1 minute after becoming ACTIVE. After that, they are not in a committed period anymore and can be removed any time.
TRIAL Trial commitments have a committed period of 182 days after becoming ACTIVE. After that, they are converted to a new commitment based on the renewal_plan. Default renewal_plan for Trial commitment is Flex so that it can be deleted right after committed period ends.
MONTHLY Monthly commitments have a committed period of 30 days after becoming ACTIVE. After that, they are not in a committed period anymore and can be removed any time.
ANNUAL Annual commitments have a committed period of 365 days after becoming ACTIVE. After that they are converted to a new commitment based on the renewal_plan.

State

Capacity commitment can either become ACTIVE right away or transition from PENDING to ACTIVE or FAILED.

Enums
STATE_UNSPECIFIED Invalid state value.
PENDING Capacity commitment is pending provisioning. Pending capacity commitment does not contribute to the parent's slot_capacity.
ACTIVE Once slots are provisioned, capacity commitment becomes active. slot_count is added to the parent's slot_capacity.
FAILED Capacity commitment is failed to be activated by the backend.

CreateAssignmentRequest

The request for ReservationService.CreateAssignment. Note: "bigquery.reservationAssignments.create" permission is required on the related assignee.

Fields
parent

string

Required. The parent resource name of the assignment E.g.: projects/myproject/locations/US/reservations/team1-prod

Authorization requires the following IAM permission on the specified resource parent:

  • bigquery.reservationAssignments.create
assignment

Assignment

Assignment resource to create.

CreateCapacityCommitmentRequest

The request for ReservationService.CreateCapacityCommitment.

Fields
parent

string

Required. Resource name of the parent reservation. E.g., projects/myproject/locations/US
capacity_commitment

CapacityCommitment

Content of the capacity commitment to create.
enforce_single_admin_project_per_org

bool

If true, fail the request if another project in the organization has a capacity commitment.

CreateReservationRequest

The request for ReservationService.CreateReservation.

Fields
parent

string

Required. Project, location. E.g., projects/myproject/locations/US
reservation_id

string

The reservation ID. This field must only contain lower case alphanumeric characters or dash. Max length is 64 characters.
reservation

Reservation

Content of the new reservation to create.

DeleteAssignmentRequest

The request for ReservationService.DeleteAssignment. Note: "bigquery.reservationAssignments.delete" permission is required on the related assignee.

Fields
name

string

Required. Name of the resource, e.g.: projects/myproject/locations/US/reservations/team1-prod/assignments/123

Authorization requires the following IAM permission on the specified resource name:

  • bigquery.reservationAssignments.delete

DeleteCapacityCommitmentRequest

The request for ReservationService.DeleteCapacityCommitment.

Fields
name

string

Required. Resource name of the capacity commitment to delete. E.g., projects/myproject/locations/US/capacityCommitments/123

DeleteReservationRequest

The request for ReservationService.DeleteReservation.

Fields
name

string

Required. Resource name of the reservation to retrieve. E.g., projects/myproject/locations/US/reservations/team1-prod

GetBiReservationRequest

A request to get a singleton BI reservation.

Fields
name

string

Required. Name of the requested reservation, for example: projects/{project_id}/locations/{location_id}/bireservation

Authorization requires the following IAM permission on the specified resource name:

  • bi.reservations.get

GetCapacityCommitmentRequest

The request for ReservationService.GetCapacityCommitment.

Fields
name

string

Required. Resource name of the capacity commitment to retrieve. E.g., projects/myproject/locations/US/capacityCommitments/123

GetReservationRequest

The request for ReservationService.GetReservation.

Fields
name

string

Required. Resource name of the reservation to retrieve. E.g., projects/myproject/locations/US/reservations/team1-prod

ListAssignmentsRequest

The request for ReservationService.ListAssignments.

Fields
parent

string

Required. The parent resource name e.g.: projects/myproject/locations/US/reservations/team1-prod Or: projects/myproject/locations/US/reservations/-

Authorization requires the following IAM permission on the specified resource parent:

  • bigquery.reservationAssignments.list
page_size

int32

The maximum number of items to return.
page_token

string

The next_page_token value returned from a previous List request, if any.

ListAssignmentsResponse

The response for ReservationService.ListAssignments.

Fields
assignments[]

Assignment

List of assignments visible to the user.
next_page_token

string

Token to retrieve the next page of results, or empty if there are no more results in the list.

ListCapacityCommitmentsRequest

The request for ReservationService.ListCapacityCommitments.

Fields
parent

string

Required. Resource name of the parent reservation. E.g., projects/myproject/locations/US
page_size

int32

The maximum number of items to return.
page_token

string

The next_page_token value returned from a previous List request, if any.

ListCapacityCommitmentsResponse

The response for ReservationService.ListCapacityCommitments.

Fields
capacity_commitments[]

CapacityCommitment

List of capacity commitments visible to the user.
next_page_token

string

Token to retrieve the next page of results, or empty if there are no more results in the list.

ListReservationsRequest

The request for ReservationService.ListReservations.

Fields
parent

string

Required. The parent resource name containing project and location, e.g.: "projects/myproject/locations/US"
page_size

int32

The maximum number of items to return.
page_token

string

The next_page_token value returned from a previous List request, if any.
filter

string

Can be used to filter out reservations based on names, capacity, etc, e.g.: filter="reservation.slot_capacity > 200" filter="reservation.name = "*dev/*"" Advanced filtering syntax can be here.

ListReservationsResponse

The response for ReservationService.ListReservations.

Fields
reservations[]

Reservation

List of reservations visible to the user.
next_page_token

string

Token to retrieve the next page of results, or empty if there are no more results in the list.

MergeCapacityCommitmentsRequest

The request for ReservationService.MergeCapacityCommitments.

Fields
parent

string

Parent resource that identifies admin project and location e.g., projects/myproject/locations/us
capacity_commitment_ids[]

string

Ids of capacity commitments to merge. These capacity commitments must exist under admin project and location specified in the parent.

MoveAssignmentRequest

The request for ReservationService.MoveAssignment. Note: "bigquery.reservationAssignments.create" permission is required on the destination_id. Note: "bigquery.reservationAssignments.create" and "bigquery.reservationAssignments.delete" permission is required on the related assignee.

Fields
name

string

Required. The resource name of the assignment, e.g.: projects/myproject/locations/US/reservations/team1-prod/assignments/123

Authorization requires the following IAM permission on the specified resource name:

  • bigquery.reservationAssignments.delete
destination_id

string

The new reservation ID, e.g.: projects/myotherproject/locations/US/reservations/team2-prod

Reservation

A reservation is a mechanism used to guarantee slots to users.

Fields
name

string

The resource name of the reservation, e.g., "projects/*/locations/*/reservations/team1-prod".
slot_capacity

int64

Minimum slots available to this reservation. A slot is a unit of computational power in BigQuery, and serves as the unit of parallelism. Queries using this reservation might use more slots during runtime if ignore_idle_slots is set to false. If the new reservation's slot capacity exceed the parent's slot capacity or if total slot capacity of the new reservation and its siblings exceeds the parent's slot capacity, the request will fail with google.rpc.Code.RESOURCE_EXHAUSTED.
ignore_idle_slots

bool

If false, any query using this reservation will use idle slots from other reservations within the same admin project. If true, a query using this reservation will execute with the slot capacity specified above at most.

SearchAssignmentsRequest

The request for ReservationService.SearchAssignments. Note: "bigquery.reservationAssignments.search" permission is required on the related assignee.

Fields
parent

string

Required. The resource name of the admin project(containing project and location), e.g.: "projects/myproject/locations/US".
query

string

Please specify resource name as assignee in the query. e.g., "assignee=projects/myproject" "assignee=folders/123" "assignee=organizations/456"
page_size

int32

The maximum number of items to return.
page_token

string

The next_page_token value returned from a previous List request, if any.

SearchAssignmentsResponse

The response for ReservationService.SearchAssignments.

Fields
assignments[]

Assignment

List of assignments visible to the user.
next_page_token

string

Token to retrieve the next page of results, or empty if there are no more results in the list.

SplitCapacityCommitmentRequest

The request for ReservationService.SplitCapacityCommitment.

Fields
name

string

Required. The resource name e.g.,: projects/myproject/locations/US/capacityCommitments/123

Authorization requires the following IAM permission on the specified resource name:

  • bigquery.capacityCommitments.update
slot_count

int64

Number of slots in the capacity commitment after the split.

SplitCapacityCommitmentResponse

The response for ReservationService.SplitCapacityCommitment.

Fields
first

CapacityCommitment

First capacity commitment, result of a split.
second

CapacityCommitment

Second capacity commitment, result of a split.

UpdateBiReservationRequest

A request to update a BI reservation.

Fields
reservation

BiReservation

A reservation to update.

Authorization requires the following IAM permission on the specified resource reservation:

  • bi.reservations.update
update_mask

FieldMask

A list of fields to be updated in this request.

UpdateCapacityCommitmentRequest

The request for ReservationService.UpdateCapacityCommitment.

Fields
capacity_commitment

CapacityCommitment

Content of the capacity commitment to update.
update_mask

FieldMask

Standard field mask for the set of fields to be updated.

UpdateReservationRequest

The request for ReservationService.UpdateReservation.

Fields
reservation

Reservation

Content of the reservation to update.
update_mask

FieldMask

Standard field mask for the set of fields to be updated.