Trabajar con reservas de ranuras heredadas

Nota: Las reservas heredadas, incluido el acceso a la facturación de tarifa plana o ciertas duraciones de compromisos, solo están disponibles para los clientes incluidos en la lista de entidades permitidas. Para determinar si tienes acceso a estas funciones heredadas, comunícate con tu administrador. El modelo de facturación de tarifa plana define cómo se te factura por el procesamiento, pero las reservas y los compromisos de tasa fija funcionan como ranuras de la edición Enterprise.

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

Crea una reserva con ranuras dedicadas

Selecciona una de las opciones siguientes:

Console

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

   Ir a BigQuery

2. En el panel de navegación, ve a la sección Administración de capacidad.

3. Haz clic en Crear reserva.

4. En el campo Nombre de la reserva, ingresa un nombre para la reserva.

5. En la lista desplegable Ubicación, selecciona ubicación.

6. En la sección Modelo de capacidad, selecciona el modelo de capacidad.

7. Si seleccionas la opción Tarifa plana, en Ranuras base, ingresa la cantidad de ranuras para la reserva.

   1. En la lista Selector de tamaño máximo de reserva, selecciona el tamaño máximo de reserva.

   2. En el campo Ranuras de referencia, ingresa la cantidad de ranuras del modelo de referencia para la reserva (opcional). Para usar solo la capacidad de ranura especificada, haz clic en el botón de activación Ignorar ranuras inactivas.

      La cantidad de ranuras con ajuste de escala automático disponibles se determina restando el valor de las ranuras del modelo de referencia del valor de 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.

8. Para inhabilitar el uso compartido de ranuras inactivas, haz clic en el botón de activación Ignora las ranuras inactivas.

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

10. Haz clic en Guardar.

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

SQL

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

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

   Ir a BigQuery

2. En el editor de consultas, escribe la siguiente oración:

   CREATE RESERVATION
     `ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME`
   OPTIONS (
     slot_capacity = NUMBER_OF_BASELINE_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_BASELINE_SLOTS: es la cantidad de ranuras del modelo de referencia que asignarás a la reserva. 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. Esto es igual al valor del tamaño máximo de la reserva menos la cantidad de ranuras del modelo de referencia.

3. 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_BASELINE_SLOTS \
    --ignore_idle_slots=false \
    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_BASELINE_SLOTS es la cantidad de ranuras de referencia que asignarás a la reserva.

• 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. Esto es igual al valor del tamaño máximo de la reserva menos la cantidad de ranuras del modelo de referencia.

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

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.

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

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

   Ir a BigQuery

2. En el panel de navegación, ve a la sección Administración de capacidad.

3. Haz clic en la pestaña Reservas.

4. Busca la reserva que deseas actualizar.

5. Expande la opción Actions.

6. Haz clic en Editar.

7. En el diálogo Selector de tamaño máximo de reserva, ingresa el tamaño máximo de la reserva.

8. En el campo Ranuras de referencia, ingresa la cantidad de ranuras de referencia.

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

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

   Ir a BigQuery

2. 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_BASELINE_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_BASELINE_SLOTS es la cantidad de ranuras de referencia que asignarás a la reserva.

3. 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_BASELINE_SLOTS \
    --reservation RESERVATION_NAME

Reemplaza lo siguiente:

• ADMIN_PROJECT_ID: El ID del proyecto
• LOCATION: la ubicación de la reserva
• NUMBER_OF_BASELINE_SLOTS es la cantidad de ranuras de referencia que asignarás a 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. 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.

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

   Ir a BigQuery

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

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

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

   Ir a BigQuery

2. En el panel de navegación, ve a la sección Administración de capacidad.

3. Haz clic en la pestaña Reservas.

4. Busca la reserva que deseas borrar.

5. Expande la opción Actions.

6. Haz clic en Borrar.

7. En el cuadro de diálogo Borrar reserva, haz clic en Borrar.

SQL

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

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

   Ir a BigQuery

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

3. 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}")

Agrega la API de BigQuery Reservation a los Controles del servicio de VPC

Nota: Es posible que esta función no esté disponible cuando se usan reservas que se crearon con determinadas ediciones de BigQuery. Para obtener más información sobre qué funciones están habilitadas en cada edición, consulta Introducción a las ediciones de BigQuery.

La API de BigQuery Reservation admite los Controles del servicio de VPC. Para integrar la API de BigQuery Reservation en los Controles del servicio de VPC, sigue las instrucciones en Crea un perímetro de servicio y agrega la API de BigQuery Reservation a los servicios protegidos.

Un perímetro de servicio protege el acceso a las reservas, los compromisos y las asignaciones dentro de los proyectos de administración que se especifican en el perímetro. Cuando se crea una asignación, los Controles del servicio de VPC protegen el proyecto de administración y el proyecto, la carpeta y la organización del usuario asignado.