Trabajar con reservas de ranuras

La API de BigQuery Reservation te permite comprar ranuras dedicadas (llamadas compromisos), crear grupos de ranuras (llamadas reservas), y asignar proyectos, carpetas y organizaciones a esas reservas.

Las reservas te permiten asignar una cantidad dedicada de ranuras a una carga de trabajo. Por ejemplo, es posible que no desees que una carga de trabajo de producción compita con cargas de trabajo de prueba para obtener ranuras. Puedes crear una reserva llamada prod y asignarle tus cargas de trabajo de producción. Para obtener más información, consulta Reservas.

Crear reservas

Permisos necesarios

Para crear una reserva, necesitas el siguiente permiso de Identity and Access Management (IAM):

bigquery.reservations.create en el proyecto de administración que mantiene la propiedad de los compromisos.

Cada una de los siguientes roles predefinidos de IAM incluye este permiso:

BigQuery Resource Editor
BigQuery Resource Admin

Para obtener más información sobre las funciones de IAM en BigQuery, consulta Funciones y permisos predefinidos.

Crea una reserva con ranuras dedicadas

Selecciona una de las opciones siguientes:

Console

En la consola de Google Cloud, ve a la página de BigQuery.

Ir a BigQuery
En el panel de navegación, ve a la sección Administración de capacidad y, luego, haz clic en Crear reserva.
En el campo Nombre de la reserva, ingresa un nombre para la reserva.
En la lista desplegable Ubicación, selecciona ubicación. Si seleccionas una ubicación de BigQuery Omni, la opción de edición se limita a Enterprise Edition.
En la lista Edición, selecciona la edición. El ajuste de escala automático solo está disponible dentro de una edición. Para obtener más información, consulta Introducción a las ediciones de BigQuery.
En la lista Selector de tamaño máximo de reserva, selecciona el tamaño máximo de reserva.
En el campo Ranuras de referencia, ingresa la cantidad de ranuras del modelo de referencia para la reserva (opcional).

La cantidad de ranuras disponibles con ajuste de escala automático se determina restando el valor de las ranuras del modelo de referencia del tamaño máximo de la reserva. Por ejemplo, si creas una reserva con 100 ranuras de referencia y un tamaño máximo de reserva de 400, la reserva tiene 300 ranuras de ajuste de escala automático. Para obtener más información sobre las ranuras de referencia, consulta Usa reservas con ranuras de referencia y de ajuste de escala automático.
Para inhabilitar el uso compartido de ranuras inactivas y utilizar solamente la capacidad de ranura especificada, haz clic en el botón de activación Ignorar ranuras inactivas.
Para expandir la sección Configuración avanzada, haz clic en la flecha de expansión .
Opcional: Para configurar la simultaneidad de los trabajos de destino, haz clic en el botón de activación Anular la simultaneidad automática del trabajo de destino y, luego, ingresa la simultaneidad de los trabajos de destino.
El desglose de ranuras se muestra en la tabla Estimación de costos. Se muestra un resumen de la reserva en la tabla Resumen de capacidad.
Haz clic en Guardar.

La reserva nueva se puede ver en la pestaña Reservas de ranuras.

SQL

Para crear una reserva, usa la declaración DDL CREATE RESERVATION.

En la consola de Google Cloud, ve a la página de BigQuery.

Ir a BigQuery
En el editor de consultas, escribe la siguiente oración:
```
CREATE RESERVATION
  `ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME`
OPTIONS (
  slot_capacity = NUMBER_OF_SLOTS,
  edition = EDITION,
  autoscale_max_slots = NUMBER_OF_AUTOSCALING_SLOTS);
```
Reemplaza lo siguiente:
- ADMIN_PROJECT_ID por el ID del proyecto de administración que posee el recurso de reserva
- LOCATION: Es la ubicación de la reserva. Si seleccionas una ubicación de BigQuery Omni, la opción de edición se limita a Enterprise Edition.
- RESERVATION_NAME por el nombre de la reserva
  
  Debe comenzar y terminar con una letra minúscula o un número, y contener solo letras minúsculas, números y guiones.
- NUMBER_OF_SLOTS es la cantidad de ranuras que asignarás a la reserva. Debe haber suficientes ranuras sin asignar en el compromiso. No puedes configurar las opciones slot_capacity y edition en la misma reserva.
- EDITION: es la edición de la reserva. Asignar una reserva a una edición incluye cambios en los atributos y los precios. Para obtener más información, consulta Introducción a las ediciones de BigQuery.
- NUMBER_OF_AUTOSCALING_SLOTS es la cantidad de ranuras de ajuste de escala automático asignadas a la reserva. Solo está disponible cuando se especifica la opción edition.
Haz clic en Ejecutar.

Si deseas obtener información sobre cómo ejecutar consultas, visita Ejecuta una consulta interactiva.

bq

Para crear una reserva, usa el comando bq mk con la marca --reservation:

bq mk \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --reservation \
    --slots=NUMBER_OF_SLOTS \
    --ignore_idle_slots=false \
    --edition=EDITION \
    --autoscale_max_slots=NUMBER_OF_AUTOSCALING_SLOTS \
    RESERVATION_NAME

Reemplaza lo siguiente:

ADMIN_PROJECT_ID: El ID del proyecto
LOCATION por la ubicación de la reserva. Si seleccionas una ubicación de BigQuery Omni, la opción de edición se limita a Enterprise Edition.
NUMBER_OF_SLOTS es la cantidad de ranuras que asignarás a la reserva.

Debe haber suficientes ranuras sin asignar en el compromiso.
RESERVATION_NAME: el nombre de la reserva
EDITION: es la edición de la reserva. Asignar una reserva a una edición incluye cambios en los atributos y los precios. Para obtener más información, consulta Introducción a las ediciones de BigQuery.
NUMBER_OF_AUTOSCALING_SLOTS es la cantidad de ranuras de ajuste de escala automático asignadas a la reserva. Solo está disponible cuando se especifica la opción edition.

Para obtener más información sobre la marca --ignore_idle_slots, consulta Ranuras inactivas. El valor predeterminado es false.

Terraform

Usa el recurso google_bigquery_reservation.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se crea una reserva llamada my-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
  }
}

Para aplicar tu configuración de Terraform en un proyecto de Google Cloud, completa los pasos de las siguientes secciones.

Prepara Cloud Shell

Inicia Cloud Shell
Establece el proyecto de Google Cloud predeterminado en el que deseas aplicar tus configuraciones de Terraform.

Solo necesitas ejecutar este comando una vez por proyecto y puedes ejecutarlo en cualquier directorio.
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
```
Las variables de entorno se anulan si configuras valores explícitos en el archivo de configuración de Terraform.

Prepara el directorio

Cada archivo de configuración de Terraform debe tener su propio directorio (también llamado módulo raíz).

En Cloud Shell, crea un directorio y un archivo nuevo dentro de ese directorio. El nombre del archivo debe tener la extensión .tf, por ejemplo, main.tf. En este instructivo, el archivo se denomina main.tf.
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
Si sigues un instructivo, puedes copiar el código de muestra en cada sección o paso.

Copia el código de muestra en el main.tf recién creado.

De manera opcional, copia el código de GitHub. Esto se recomienda cuando el fragmento de Terraform es parte de una solución de extremo a extremo.
Revisa y modifica los parámetros de muestra que se aplicarán a tu entorno.
Guarda los cambios.
Inicialice Terraform. Solo debes hacerlo una vez por directorio.
```
terraform init
```
De manera opcional, incluye la opción -upgrade para usar la última versión del proveedor de Google:
```
terraform init -upgrade
```

Aplica los cambios

Revisa la configuración y verifica que los recursos que creará o actualizará Terraform coincidan con tus expectativas:
```
terraform plan
```
Corrige la configuración según sea necesario.
Para aplicar la configuración de Terraform, ejecuta el siguiente comando y, luego, escribe yes cuando se te solicite:
```
terraform apply
```
Espera hasta que Terraform muestre el mensaje “¡Aplicación completa!”.
Abre tu proyecto de Google Cloud para ver los resultados. En la consola de Google Cloud, navega a tus recursos en la IU para asegurarte de que Terraform los haya creado o actualizado.

Python

Instala el paquete google-cloud-bigquery-reservation antes de usar esta muestra de código. Crea un ReservationServiceClient. Describe la reserva que deseas crear con una reserva. Cree la reserva con el método create_reservation.

# TODO(developer): Set project_id to the project ID containing the
# reservation.
project_id = "your-project-id"

# TODO(developer): Set location to the location of the reservation.
# See: https://cloud.google.com/bigquery/docs/locations for a list of
# available locations.
location = "US"

# TODO(developer): Set reservation_id to a unique ID of the reservation.
reservation_id = "sample-reservation"

# TODO(developer): Set slot_capicity to the number of slots in the
# reservation.
slot_capacity = 100

# TODO(developer): Choose a transport to use. Either 'grpc' or 'rest'
transport = "grpc"

# ...

from google.cloud.bigquery_reservation_v1.services import reservation_service
from google.cloud.bigquery_reservation_v1.types import (
    reservation as reservation_types,
)

reservation_client = reservation_service.ReservationServiceClient(
    transport=transport
)

parent = reservation_client.common_location_path(project_id, location)

reservation = reservation_types.Reservation(slot_capacity=slot_capacity)
reservation = reservation_client.create_reservation(
    parent=parent,
    reservation=reservation,
    reservation_id=reservation_id,
)

print(f"Created reservation: {reservation.name}")

Actualiza las reservas

Puedes realizar las siguientes actualizaciones en una reserva:

Agrega o quita ranuras para cambiar el tamaño de la reserva.
Configura si las consultas en esta reserva usan ranuras inactivas.
Cambia la cantidad de ranuras de referencia o con ajuste de escala automático asignadas a una reserva.
Actualiza a una edición superior. No puedes cambiar una reserva existente a una edición inferior.
Configura la simultaneidad de los trabajos de destino.

Permisos necesarios

Para actualizar una reserva, necesitas el siguiente permiso de Identity and Access Management (IAM):

bigquery.reservations.update en el proyecto de administración que mantiene la propiedad de los compromisos.

Cada una de los siguientes roles predefinidos de IAM incluye este permiso:

BigQuery Admin
BigQuery Resource Admin
BigQuery Resource Editor

Para obtener más información sobre las funciones de IAM en BigQuery, consulta Funciones y permisos predefinidos.

Cambia el tamaño de una reserva

Puedes agregar o quitar ranuras de una reserva existente.

Console

En la consola de Google Cloud, ve a la página de BigQuery.

Ir a BigQuery
En el panel de navegación, ve a la sección Administración de capacidad.
Haz clic en la pestaña Reservas de ranuras.
Busca la reserva que deseas actualizar.
Expande la opción Actions.
Haga clic en Editar.
En el diálogo Selector de tamaño máximo de reserva, ingresa el tamaño máximo de la reserva.
En el campo Ranuras de referencia, ingresa la cantidad de ranuras del modelo de referencia.
Para expandir la sección Configuración avanzada, haz clic en la flecha de expansión .
Opcional: Para configurar la simultaneidad de los trabajos de destino, haz clic en el botón de activación Anular la simultaneidad automática del trabajo de destino y, luego, ingresa la simultaneidad de los trabajos de destino.
Haz clic en Guardar.

SQL

Para cambiar el tamaño de una reserva, usa la declaración del lenguaje de definición de datos ALTER RESERVATION SET OPTIONS (DDL).

En la consola de Google Cloud, ve a la página de BigQuery.

Ir a BigQuery
En el editor de consultas, escribe la siguiente oración:
```
ALTER RESERVATION
  `ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME`
SET OPTIONS (
  slot_capacity = NUMBER_OF_SLOTS,
  autoscale_max_slots = NUMBER_OF_AUTOSCALING_SLOTS);
```
Reemplaza lo siguiente:
- ADMIN_PROJECT_ID por el ID del proyecto de administración que posee el recurso de reserva
- LOCATION por la ubicación de la reserva, por ejemplo, europe-west9.
- RESERVATION_NAME por el nombre de la reserva. Debe comenzar y terminar con una letra minúscula o un número, y contener solo letras minúsculas, números y guiones.
- NUMBER_OF_SLOTS es la cantidad de ranuras que asignarás a la reserva.
- NUMBER_OF_AUTOSCALING_SLOTS es la cantidad de ranuras de ajuste de escala automático asignadas a la reserva. Esta opción solo está disponible para reservas con un edition.
Haz clic en Ejecutar.

Si deseas obtener información sobre cómo ejecutar consultas, visita Ejecuta una consulta interactiva.

bq

Para actualizar el tamaño de una reserva, usa el comando bq update con la marca --reservation:

bq update \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --slots=NUMBER_OF_SLOTS \
    --autoscale_max_slots=NUMBER_OF_AUTOSCALING_SLOTS \
    --reservation RESERVATION_NAME

Reemplaza lo siguiente:

ADMIN_PROJECT_ID: El ID del proyecto
LOCATION: la ubicación de la reserva
NUMBER_OF_SLOTS es la cantidad de ranuras que asignarás a la reserva.
RESERVATION_NAME: el nombre de la reserva
NUMBER_OF_AUTOSCALING_SLOTS es la cantidad de ranuras de ajuste de escala automático asignadas a la reserva. Solo está disponible cuando se especifica la opción edition.

Python

Instala el paquete google-cloud-bigquery-reservation antes de usar esta muestra de código. Crea un ReservationServiceClient. Describe las propiedades actualizadas con una propiedad Reservation y FieldMask.paths. Actualiza la reserva con el método update_reservation.

# TODO(developer): Set project_id to the project ID containing the
# reservation.
project_id = "your-project-id"

# TODO(developer): Set location to the location of the reservation.
# See: https://cloud.google.com/bigquery/docs/locations for a list of
# available locations.
location = "US"

# TODO(developer): Set reservation_id to a unique ID of the reservation.
reservation_id = "sample-reservation"

# TODO(developer): Set slot_capicity to the new number of slots in the
# reservation.
slot_capacity = 50

# TODO(developer): Choose a transport to use. Either 'grpc' or 'rest'
transport = "grpc"

# ...

from google.cloud.bigquery_reservation_v1.services import reservation_service
from google.cloud.bigquery_reservation_v1.types import (
    reservation as reservation_types,
)
from google.protobuf import field_mask_pb2

reservation_client = reservation_service.ReservationServiceClient(
    transport=transport
)

reservation_name = reservation_client.reservation_path(
    project_id, location, reservation_id
)
reservation = reservation_types.Reservation(
    name=reservation_name,
    slot_capacity=slot_capacity,
)
field_mask = field_mask_pb2.FieldMask(paths=["slot_capacity"])
reservation = reservation_client.update_reservation(
    reservation=reservation, update_mask=field_mask
)

print(f"Updated reservation: {reservation.name}")
print(f"\tslot_capacity: {reservation.slot_capacity}")

Configura si las consultas usan ranuras inactivas

La marca --ignore_idle_slots controla si las consultas que se ejecutan en una reserva pueden usar ranuras inactivas de otras reservas. Para obtener más información, consulta Ranuras inactivas. Puedes actualizar esta configuración en una reserva existente.

Para actualizar una reserva, usa el comando bq update con la marca --reservation. En el siguiente ejemplo, se establece --ignore_idle_slots como true, lo que significa que la reserva solo usará las ranuras asignadas a la reserva.

bq update \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --ignore_idle_slots=true \
    --reservation RESERVATION_NAME

Reemplaza lo siguiente:

ADMIN_PROJECT_ID: El ID del proyecto
LOCATION: la ubicación de la reserva
RESERVATION_NAME: el nombre de la reserva

Enumera la configuración de ranuras inactivas

Para enumerar la configuración de las ranuras inactivas de una reserva, haz lo siguiente:

SQL

Consulta la columna ignore_idle_slots de la vista INFORMATION_SCHEMA.RESERVATIONS_BY_PROJECT.

En la consola de Google Cloud, ve a la página de BigQuery.

Ir a BigQuery
En el editor de consultas, escribe la siguiente oración:
```
SELECT
  reservation_name,
  ignore_idle_slots
FROM
  `ADMIN_PROJECT_ID.region-LOCATION`.INFORMATION_SCHEMA.RESERVATIONS_BY_PROJECT;
```
Reemplaza lo siguiente:
- ADMIN_PROJECT_ID por el ID del proyecto de administración que posee los recursos de reserva
- LOCATION: por la ubicación de las reservas
Haz clic en Ejecutar.

Si deseas obtener información sobre cómo ejecutar consultas, visita Ejecuta una consulta interactiva.

bq

Usa el comando bq ls con la marca --reservation:

bq ls --reservation \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION

Reemplaza lo siguiente:

ADMIN_PROJECT_ID por el ID del proyecto de administración que posee los recursos de reserva
LOCATION: por la ubicación de las reservas

El campo ignoreIdleSlots contiene la configuración.

Borrar reservas

Si borras una reserva, los trabajos que se ejecutan actualmente con ranuras de esa reserva fallarán. Para evitar errores, permite que los trabajos en ejecución se completen antes de borrar la reserva.

Permisos necesarios

Para borrar una reserva, necesitas el siguiente permiso de Identity and Access Management (IAM):

bigquery.reservations.delete en el proyecto de administración que mantiene la propiedad de los compromisos.

Cada una de los siguientes roles predefinidos de IAM incluye este permiso:

BigQuery Admin
BigQuery Resource Admin
BigQuery Resource Editor

Para obtener más información sobre las funciones de IAM en BigQuery, consulta Funciones y permisos predefinidos.

Borra una reserva

Console

En la consola de Google Cloud, ve a la página de BigQuery.

Ir a BigQuery
En el panel de navegación, ve a la sección Administración de capacidad.
Haz clic en la pestaña Reservas.
Busca la reserva que deseas borrar.
Expande la opción Actions.
Haz clic en Borrar.
En el cuadro de diálogo Borrar reserva, haz clic en Borrar.

SQL

Para borrar una reserva, usa la declaración DDL DROP RESERVATION.

En la consola de Google Cloud, ve a la página de BigQuery.

Ir a BigQuery
En el editor de consultas, escribe la siguiente oración:
```
DROP RESERVATION
  `ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME`;
```
Reemplaza lo siguiente:
- ADMIN_PROJECT_ID por el ID del proyecto de administración que posee el recurso de reserva
- LOCATION: la ubicación de la reserva
- RESERVATION_NAME es el ID de la reserva.
Haz clic en Ejecutar.

Si deseas obtener información sobre cómo ejecutar consultas, visita Ejecuta una consulta interactiva.

bq

Para borrar una reserva, usa el comando bq rm con la marca --reservation:

bq rm \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --reservation RESERVATION_NAME

Reemplaza lo siguiente:

ADMIN_PROJECT_ID por el ID del proyecto de administración que posee el recurso de reserva
LOCATION: la ubicación de la reserva
RESERVATION_NAME: el nombre de la reserva

Python

Instala el paquete google-cloud-bigquery-reservation antes de usar esta muestra de código. Crea un ReservationServiceClient. Borra la reserva con el método delete_reservation.

# TODO(developer): Set project_id to the project ID containing the
# reservation.
project_id = "your-project-id"

# TODO(developer): Set location to the location of the reservation.
# See: https://cloud.google.com/bigquery/docs/locations for a list of
# available locations.
location = "US"

# TODO(developer): Set reservation_id to a unique ID of the reservation.
reservation_id = "sample-reservation"

# TODO(developer): Choose a transport to use. Either 'grpc' or 'rest'
transport = "grpc"

# ...

from google.cloud.bigquery_reservation_v1.services import reservation_service

reservation_client = reservation_service.ReservationServiceClient(
    transport=transport
)
reservation_name = reservation_client.reservation_path(
    project_id, location, reservation_id
)
reservation_client.delete_reservation(name=reservation_name)

print(f"Deleted reservation: {reservation_name}")