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 | |
---|---|
Returns
|
CreateReservation | |
---|---|
Creates a new reservation resource.
|
DeleteAssignment | |
---|---|
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.
|
DeleteCapacityCommitment | |
---|---|
Deletes a capacity commitment. Attempting to delete capacity commitment before its commitment_end_time will fail with the error code
|
DeleteReservation | |
---|---|
Deletes a reservation. Returns
|
GetCapacityCommitment | |
---|---|
Returns information about the capacity commitment.
|
GetReservation | |
---|---|
Returns information about the reservation.
|
ListAssignments | |
---|---|
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.
|
ListCapacityCommitments | |
---|---|
Lists all the capacity commitments for the admin project.
|
ListReservations | |
---|---|
Lists all the reservations for the project in the specified location.
|
MoveAssignment | |
---|---|
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.
|
SearchAssignments | |
---|---|
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.
|
UpdateReservation | |
---|---|
Updates an existing reservation resource.
|
Assignment
A Assignment allows a project to submit jobs of a certain type using slots from the specified reservation.
Fields | |
---|---|
name |
Output only. Name of the resource. E.g.: projects/myproject/locations/US/reservations/team1-prod/assignments/123. |
assignee |
The resource which will use the reservation. E.g. projects/myproject, folders/123, organizations/456. |
job_type |
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 |
Output only. The resource name of the capacity commitment, e.g., projects/myproject/locations/US/capacityCommitments/123 |
slot_count |
Number of slots in this commitment. |
plan |
Capacity commitment commitment plan. |
state |
Output only. State of the commitment. |
commitment_end_time |
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 |
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
|
assignment |
Assignment resource to create. |
CreateCapacityCommitmentMetadata
The metadata for operation returned from ReservationService.CreateCapacityCommitment
.
Fields | |
---|---|
capacity_commitment |
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 |
Project, location. E.g., projects/myproject/locations/US |
reservation_id |
The reservation ID. This field must only contain alphanumeric characters or dash. |
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 |
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
|
DeleteCapacityCommitmentRequest
The request for ReservationService.DeleteCapacityCommitment
.
Fields | |
---|---|
name |
Resource name of the capacity commitment to delete. E.g., projects/myproject/locations/US/capacityCommitments/123 |
DeleteReservationRequest
The request for ReservationService.DeleteReservation
.
Fields | |
---|---|
name |
Resource name of the reservation to retrieve. E.g., projects/myproject/locations/US/reservations/team1-prod |
GetCapacityCommitmentRequest
The request for ReservationService.GetCapacityCommitment
.
Fields | |
---|---|
name |
Resource name of the capacity commitment to retrieve. E.g., projects/myproject/locations/US/capacityCommitments/123 |
GetReservationRequest
The request for ReservationService.GetReservation
.
Fields | |
---|---|
name |
Resource name of the reservation to retrieve. E.g., projects/myproject/locations/US/reservations/team1-prod |
ListAssignmentsRequest
The request for ReservationService.ListAssignments
.
Fields | |
---|---|
parent |
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
|
page_size |
The maximum number of items to return. |
page_token |
The next_page_token value returned from a previous List request, if any. |
ListAssignmentsResponse
The response for ReservationService.ListAssignments
.
Fields | |
---|---|
assignments[] |
List of assignments visible to the user. |
next_page_token |
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 |
Resource name of the parent reservation. E.g., projects/myproject/locations/US |
page_size |
The maximum number of items to return. |
page_token |
The next_page_token value returned from a previous List request, if any. |
ListCapacityCommitmentsResponse
The response for ReservationService.ListCapacityCommitments
.
Fields | |
---|---|
capacity_commitments[] |
List of capacity commitments visible to the user. |
next_page_token |
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 |
The parent resource name containing project and location, e.g.: "projects/myproject/locations/US" |
page_size |
The maximum number of items to return. |
page_token |
The next_page_token value returned from a previous List request, if any. |
filter |
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[] |
List of reservations visible to the user. |
next_page_token |
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 |
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
|
destination_id |
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 |
The resource name of the reservation, e.g., "projects/*/locations/*/reservations/team1-prod". |
slot_capacity |
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 |
ignore_idle_slots |
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 |
The resource name of the admin project(containing project and location), e.g.: "projects/myproject/locations/US". |
query |
Please specify resource name as assignee in the query. e.g., "assignee=projects/myproject" "assignee=folders/123" "assignee=organizations/456" |
page_size |
The maximum number of items to return. |
page_token |
The next_page_token value returned from a previous List request, if any. |
SearchAssignmentsResponse
The response for ReservationService.SearchAssignments
.
Fields | |
---|---|
assignments[] |
List of assignments visible to the user. |
next_page_token |
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 |
Content of the reservation to update. |
update_mask |
Standard field mask for the set of fields to be updated. |