Trabajar con asignaciones de reserva

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.

Crea asignaciones de reservas

Para usar las ranuras que compres, debes crear una asignación que asigne un proyecto, una carpeta o una organización a una reserva de ranuras.

Los proyectos usan la reserva única más específica de la jerarquía de recursos a la que están asignados. Una asignación de carpeta anula una asignación de organización y una asignación de proyecto anula una asignación de carpeta. Las asignaciones de carpetas y organizaciones no están disponibles para las reservas de edición estándar.

Para crear una asignación en una reserva, esta debe cumplir con al menos uno de los siguientes criterios:

  • Se configura con una cantidad distinta de cero de ranuras de modelo de referencia asignadas.

  • Se configura con una cantidad distinta de cero de ranuras con ajuste de escala automático.

  • Está configurada para usar ranuras inactivas, y hay ranuras inactivas disponibles en el proyecto.

Si intentas asignar un recurso a una reserva que no cumple con al menos uno de estos criterios, recibirás el siguiente mensaje: Assignment is pending, your project will be executed as on-demand.

Puedes asignar un recurso a una reserva de conmutación por error, pero la asignación se encuentra en la ubicación secundaria.

Permisos necesarios

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

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.

Asigna una organización a 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 en la tabla de reservas.

  5. Expande la opción Actions.

  6. Haz clic en Crear asignación.

  7. En la sección Crear deberes, haz clic en Explorar.

  8. Explora o busca la organización y selecciónala.

  9. En la sección Tipo de trabajo, elige un tipo de trabajo para asignar a esta reserva. Las opciones incluyen las siguientes:

    • QUERY
    • CONTINUOUS (vista previa)
    • PIPELINE
    • BACKGROUND
    • ML_EXTERNAL

    Para obtener más información sobre los tipos de trabajo, consulta Asignaciones de reserva. Este valor predeterminado es QUERY.

  10. Haz clic en Crear.

SQL

Para asignar una organización a una reserva, usa la declaración DDL CREATE ASSIGNMENT.

  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 ASSIGNMENT
      `ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME.ASSIGNMENT_ID`
    OPTIONS (
      assignee = 'organizations/ORGANIZATION_ID',
      job_type = 'JOB_TYPE');

    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 por el nombre de la reserva
    • ASSIGNMENT_ID por el ID de la asignación

      El ID debe ser único para el proyecto y la ubicación, debe empezar y terminar con una letra minúscula o un número, y contener solo letras en minúscula, números y guiones.

    • ORGANIZATION_ID por el ID de la organización
    • JOB_TYPE por el tipo de trabajo que se asignará a esta reserva, como QUERY, CONTINUOUS (versión preliminar), PIPELINE, BACKGROUND, o ML_EXTERNAL

  3. Haz clic en Ejecutar.

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

bq

Para asignar los trabajos de una organización a una reserva, usa el comando bq mk con la marca --reservation_assignment:

bq mk \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --reservation_assignment \
    --reservation_id=RESERVATION_NAME \
    --assignee_id=ORGANIZATION_ID \
    --job_type=JOB_TYPE \
    --assignee_type=ORGANIZATION

Reemplaza lo siguiente:

Cuando crees una asignación de reserva, espera al menos 5 minutos antes de ejecutar una consulta. De lo contrario, la consulta puede facturarse con precios a pedido.

Asigna un proyecto o una carpeta a 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 en la tabla de reservas.

  5. Expande la opción Actions.

  6. Haz clic en Crear asignación.

  7. En la sección Crear deberes, haz clic en Explorar.

  8. Explora o busca el proyecto o la carpeta y selecciónalo.

  9. En la sección Tipo de trabajo, elige un tipo de trabajo para asignar a esta reserva. Las opciones incluyen las siguientes:

    • QUERY
    • CONTINUOUS (vista previa)
    • PIPELINE
    • BACKGROUND
    • ML_EXTERNAL

    Para obtener más información sobre los tipos de trabajo, consulta Asignaciones de reserva. Este valor predeterminado es QUERY.

  10. Haz clic en Crear.

SQL

Para asignar un proyecto a una reserva, usa la declaración DDL CREATE ASSIGNMENT.

  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 ASSIGNMENT
      `ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME.ASSIGNMENT_ID`
    OPTIONS(
      assignee="projects/PROJECT_ID",
      job_type="JOB_TYPE");

    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 por el nombre de la reserva
    • ASSIGNMENT_ID por el ID de la asignación

      El ID debe ser único para el proyecto y la ubicación, debe empezar y terminar con una letra minúscula o un número, y contener solo letras en minúscula, números y guiones.

    • PROJECT_ID por el ID del proyecto que se asignará a la reserva
    • JOB_TYPE por el tipo de trabajo que se asignará a esta reserva, como QUERY, CONTINUOUS (versión preliminar), PIPELINE, BACKGROUND, o ML_EXTERNAL

  3. Haz clic en Ejecutar.

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

bq

Para asignar trabajos a una reserva, usa el comando bq mk con la marca --reservation_assignment:

bq mk \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --reservation_assignment \
    --reservation_id=RESERVATION_NAME \
    --assignee_id=PROJECT_ID \
    --job_type=JOB_TYPE \
    --assignee_type=PROJECT

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 por el nombre de la reserva
  • PROJECT_ID por el ID del proyecto que se asignará a esta reserva
  • JOB_TYPE: por el tipo de trabajo que se asignará a esta reserva, como QUERY, CONTINUOUS (versión preliminar), PIPELINE, BACKGROUND o ML_EXTERNAL.

Terraform

Usa el recurso google_bigquery_reservation_assignment.

.

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 asigna un proyecto a la 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
  }
}

data "google_project" "project" {}

resource "google_bigquery_reservation_assignment" "default" {
  assignee    = "projects/${data.google_project.project.project_id}"
  job_type    = "QUERY"
  reservation = google_bigquery_reservation.default.id
}

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

Prepara Cloud Shell

  1. Inicia Cloud Shell
  2. 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).

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

  3. Revisa y modifica los parámetros de muestra que se aplicarán a tu entorno.
  4. Guarda los cambios.
  5. Inicializa 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

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

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

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

Cuando crees una asignación de reserva, espera al menos 5 minutos antes de ejecutar una consulta. De lo contrario, la consulta puede facturarse con precios a pedido.

Para crear un proyecto que solo use ranuras inactivas, crea una reserva con las ranuras 0 asignadas y luego sigue los pasos anteriores para asignar el proyecto a esa reserva.

Asigna un proyecto a none

Las asignaciones a none representan la ausencia de una asignación. Los proyectos con asignaciones a none usan los precios bajo demanda.

SQL

Para asignar un proyecto a none, usa la declaración DDL CREATE ASSIGNMENT.

  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 ASSIGNMENT
      `ADMIN_PROJECT_ID.region-LOCATION.none.ASSIGNMENT_ID`
    OPTIONS(
      assignee="projects/PROJECT_ID",
      job_type="QUERY");

    Reemplaza lo siguiente:

    • LOCATION: La ubicación de los trabajos que deben usar los precios según demanda
    • ASSIGNMENT_ID por el ID de la asignación

      El ID debe ser único para el proyecto y la ubicación, debe empezar y terminar con una letra minúscula o un número, y contener solo letras en minúscula, números y guiones.

    • PROJECT_ID por el ID del proyecto que se asignará 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 asignar un proyecto a none, usa el comando bq mk con la marca --reservation_assignment:

bq mk \
    --location=LOCATION \
    --reservation_assignment \
    --reservation_id=none \
    --job_type=QUERY \
    --assignee_id=PROJECT_ID \
    --assignee_type=PROJECT

Reemplaza lo siguiente:

  • LOCATION: La ubicación de los trabajos que deben usar precios según demanda
  • PROJECT_ID por el ID del proyecto que se asignará a none

Terraform

Usa el recurso google_bigquery_reservation_assignment.

.

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 asigna un proyecto a none:

data "google_project" "project" {}

resource "google_bigquery_reservation_assignment" "default" {
  assignee    = "projects/${data.google_project.project.project_id}"
  job_type    = "QUERY"
  reservation = "projects/${data.google_project.project.project_id}/locations/us/reservations/none"
}

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

Prepara Cloud Shell

  1. Inicia Cloud Shell
  2. 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).

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

  3. Revisa y modifica los parámetros de muestra que se aplicarán a tu entorno.
  4. Guarda los cambios.
  5. Inicializa 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

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

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

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

Asigna ranuras a cargas de trabajo de BigQuery ML

Los siguientes tipos de modelos de BigQuery ML usan servicios externos:

Puedes asignar ranuras reservadas a las consultas con estos servicios mediante el tipo de asignación ML_EXTERNAL. Si no se encuentra un tipo de asignación ML_EXTERNAL, el trabajo de consulta se ejecuta como a pedido.

Usa el comando bq mk con la marca --reservation_assignment y establece la marca --job_type en ML_EXTERNAL.

bq mk \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --reservation_assignment \
    --reservation_id=RESERVATION_NAME \
    --job_type=ML_EXTERNAL\
    --assignee_id=PROJECT_ID \
    --assignee_type=PROJECT

Reemplaza lo siguiente:

  • ADMIN_PROJECT_ID por el ID del proyecto al que pertenece el recurso de reserva
  • LOCATION: por la ubicación de la reserva
  • RESERVATION_NAME: por el nombre de la reserva
  • PROJECT_ID por el ID del proyecto que se asignará a esta reserva

Busca asignaciones de reservas

Permisos necesarios

Para buscar una asignación de reserva de un proyecto, organización o carpeta determinado, necesitas el siguiente permiso de Identity and Access Management (IAM):

  • bigquery.reservationAssignments.list en el proyecto de administración.

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

  • BigQuery Admin
  • BigQuery Resource Admin
  • BigQuery Resource Editor
  • BigQuery Resource Viewer
  • BigQuery User

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

Enumera la asignación de reserva de un proyecto

Puedes averiguar si tu organización, carpeta o proyecto está asignado a una reserva si haces lo siguiente:

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. En la tabla de reservas, expande una reserva para ver qué recursos se asignan a esa reserva o usa el campo Filtro para filtrar por nombre del recurso.

SQL

Para encontrar a qué reserva están asignados los trabajos de consulta de tu proyecto, consulta la vista INFORMATION_SCHEMA.ASSIGNMENTS_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
        assignment_id
      FROM `region-LOCATION`.INFORMATION_SCHEMA.ASSIGNMENTS_BY_PROJECT
      WHERE
        assignee_id = 'PROJECT_ID'
        AND job_type = 'JOB_TYPE';

    Reemplaza lo siguiente:

    • LOCATION: la ubicación de las reservas que se verán
    • ADMIN_PROJECT_ID por el ID del proyecto de administración que posee el recurso de reserva
    • PROJECT_ID por el ID del proyecto que se asignará a la reserva
    • JOB_TYPE por el tipo de trabajo que se asignará a esta reserva, como QUERY, CONTINUOUS (versión preliminar), PIPELINE, BACKGROUND, o ML_EXTERNAL

  3. Haz clic en Ejecutar.

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

bq

Para encontrar a qué reserva están asignados los trabajos de consulta de tu proyecto, usa el comando bq show con la marca --reservation_assignment:

bq show \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --reservation_assignment \
    --job_type=JOB_TYPE \
    --assignee_id=PROJECT_ID \
    --assignee_type=PROJECT

Reemplaza lo siguiente:

  • ADMIN_PROJECT_ID por el ID del proyecto al que pertenece el recurso de reserva
  • LOCATION: la ubicación de las reservas que se verán
  • JOB_TYPE por el tipo de trabajo que se asignará a esta reserva, como QUERY, CONTINUOUS (versión preliminar), PIPELINE, BACKGROUND, o ML_EXTERNAL
  • PROJECT_ID: El ID del proyecto

Actualiza asignaciones de reservas

Mueve una asignación a una reserva diferente

Puedes mover una asignación de una reserva a otra.

Para mover una asignación de reserva, necesitas los siguientes permisos de Identity and Access Management (IAM) en el proyecto de administración y el usuario asignado.

  • bigquery.reservationAssignments.create
  • bigquery.reservationAssignments.delete

Cada una de los siguientes roles predefinidos de IAM incluye estos permisos:

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

Para mover una asignación, usa el comando bq update:

bq update \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --reservation_assignment \
    --destination_reservation_id=DESTINATION_RESERVATION \
    ADMIN_PROJECT_ID:LOCATION.RESERVATION_NAME.ASSIGNMENT_ID

Reemplaza lo siguiente:

  • ADMIN_PROJECT_ID por el ID del proyecto al que pertenece el recurso de reserva
  • LOCATION: la ubicación de la reserva nueva.
  • RESERVATION_NAME: por la reserva desde la que se moverá la asignación
  • DESTINATION_RESERVATION por la reserva a la que se moverá la asignación.
  • ASSIGNMENT_ID por el ID de la asignación

    Para obtener el ID de asignación, consulta Enumera la asignación de reserva de un proyecto.

Borrar asignaciones de reservas

Puedes quitar un proyecto de una reserva si borras la asignación de reserva. Si un proyecto no está asignado a ninguna reserva, hereda cualquier asignación en sus organizaciones o carpetas superiores, o usa los precios según demanda si no hay asignaciones superiores.

Cuando borras una asignación de reserva, los trabajos que se ejecutan con ranuras de esa reserva continúan ejecutándose hasta que se completan.

Permisos necesarios

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

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

  • BigQuery Admin
  • BigQuery Resource Admin
  • BigQuery Resource Editor

Quita un proyecto de una reserva

Para quitar un proyecto de una reserva, haz lo siguiente:

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. En la tabla de reservas, expande la reserva para encontrar el proyecto.

  5. Expande la opción Actions.

  6. Haz clic en Borrar.

SQL

Usa la declaración DDL DROP ASSIGNMENT.

  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 ASSIGNMENT
      `ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME.ASSIGNMENT_ID`;

    Reemplaza lo siguiente:

  3. Haz clic en Ejecutar.

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

bq

Para quitar un proyecto de una reserva, usa el comando bq rm con la marca --reservation_assignment:

bq rm \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --reservation_assignment RESERVATION_NAME.ASSIGNMENT_ID

Reemplaza lo siguiente:

  • ADMIN_PROJECT_ID por el ID del proyecto al que pertenece el recurso de reserva
  • LOCATION: por la ubicación de la reserva
  • RESERVATION_NAME por el nombre de la reserva
  • ASSIGNMENT_ID por el ID de la asignación

    Para obtener el ID de asignación, consulta Encuentra la asignación de reserva de un proyecto.