Package google.cloud.bigquery.reservation.v1beta1

Index

• ReservationService (interface)
• Assignment (message)
• Assignment.JobType (enum)
• CapacityCommitment (message)
• CapacityCommitment.CommitmentPlan (enum)
• CapacityCommitment.State (enum)
• CreateAssignmentRequest (message)
• CreateCapacityCommitmentMetadata (message)
• CreateReservationRequest (message)
• DeleteAssignmentRequest (message)
• DeleteCapacityCommitmentRequest (message)
• DeleteReservationRequest (message)
• GetCapacityCommitmentRequest (message)
• GetReservationRequest (message)
• ListAssignmentsRequest (message)
• ListAssignmentsResponse (message)
• ListCapacityCommitmentsRequest (message)
• ListCapacityCommitmentsResponse (message)
• ListReservationsRequest (message)
• ListReservationsResponse (message)
• MoveAssignmentRequest (message)
• Reservation (message)
• SearchAssignmentsRequest (message)
• SearchAssignmentsResponse (message)
• UpdateReservationRequest (message)

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 minimum 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.

Some of the methods return google.longrunning.Operation as it can take a long time to process the request.

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. This check can be bypassed by setting DeleteReservationRequest.force flag to true. 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.

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/*. Wildcard "-" can be used for projects in SearchAssignmentsRequest.parent. 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.

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.

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.

CapacityCommitment

Capacity commitment is a way to purchase compute capacity for BigQuery jobs (in the form of slots) with some minimum committed period of usage. Capacity commitment is immutable and cannot be deleted until the end of the commitment period. After the end of the commitment period, slots are still available but can be freely removed any time.

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 commitment period. Capacity commitment cannot be removed before commitment_end_time. It is applicable only for ACTIVE capacity commitments and is computed as a combination of the plan and the time when the capacity commitment became ACTIVE.

CommitmentPlan

Commitment plan defines the end of the committed period.

Enums
COMMITMENT_PLAN_UNSPECIFIED	Invalid plan value. Requests with this value will be rejected with error code google.rpc.Code.INVALID_ARGUMENT.
MONTHLY	Capacity commitment cannot be removed for 30 days after becoming ACTIVE.
ANNUAL	Capacity commitment cannot be removed for 365 days after becoming ACTIVE.

State

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

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.

CreateAssignmentRequest

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

Fields
parent	string The parent resource name of the assignment E.g.: projects/myproject/location/US/reservations/team1-prod Authorization requires the following Google IAM permission on the specified resource parent: bigquery.reservationAssignments.create
assignment	Assignment Assignment resource to create.

CreateCapacityCommitmentMetadata

The metadata for operation returned from ReservationService.CreateCapacityCommitment.

Fields
capacity_commitment	string Resource name of the capacity commitment that is being created. E.g., projects/myproject/locations/US/capacityCommitments/123

CreateReservationRequest

The request for ReservationService.CreateReservation.

Fields
parent	string Project, location. E.g., projects/myproject/locations/US
reservation_id	string The reservation ID. This field must only contain alphanumeric characters or dash.
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 Name of the resource, e.g.: projects/myproject/locations/US/reservations/team1-prod/assignments/123 Authorization requires the following Google IAM permission on the specified resource name: bigquery.reservationAssignments.delete

DeleteCapacityCommitmentRequest

The request for ReservationService.DeleteCapacityCommitment.

Fields
name	string 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 Resource name of the reservation to retrieve. E.g., projects/myproject/locations/US/reservations/team1-prod

GetCapacityCommitmentRequest

The request for ReservationService.GetCapacityCommitment.

Fields
name	string 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 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 The parent resource name e.g.: projects/myproject/location/US/reservations/team1-prod Or: projects/myproject/location/US/reservations/- Authorization requires the following Google 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 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 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.

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 The resource name of the assignment, e.g.: projects/myproject/locations/US/reservations/team1-prod/assignments/123 Authorization requires the following Google 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 Maximum slots available to this reservation. A slot is a unit of computational power in BigQuery, and serves as the unit of parallelism. In a scan of a multi-partitioned table, a single slot operates on a single partition of the table. 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 true, any query using this reservation might be able to use the idle slots from other reservations within the same admin project. If false, a query using this reservation will execute with the maximum slot capacity as specified above. If not specified, default value is true.

SearchAssignmentsRequest

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

Fields
parent	string 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.

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.