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

Cette page vous a-t-elle été utile ? Évaluez-la :

Envoyer des commentaires concernant…

Besoin d'aide ? Consultez notre page d'assistance.