Programa consultas

Esta página describe cómo programar consultas recurrentes en BigQuery.

Puede programar consultas para que se ejecuten de forma recurrente. Las consultas programadas deben estar escritas en GoogleSQL, que puede incluir declaraciones en lenguaje de definición de datos (DDL) y en lenguaje de manipulación de datos (DML). Puedes organizar los resultados de las consultas por fecha y hora con la parametrización de la cadena de consulta y la tabla de destino.

Cuando creas o actualizas la programación de una consulta, la hora programada de la consulta se convierte de tu hora local a UTC. UTC no se ve afectado por el horario de verano.

Antes de comenzar

• Las consultas programadas usan las características del Servicio de transferencia de datos de BigQuery. Verifica si completaste todas las acciones obligatorias en la página sobre cómo habilitar el Servicio de transferencia de datos de BigQuery.
• Otorga funciones de Identity and Access Management (IAM) que les brindan a los usuarios los permisos necesarios para realizar cada tarea de este documento.
• Si planeas especificar una clave de encriptación administrada por el cliente (CMEK), asegúrate de que tu cuenta de servicio tenga permisos para encriptar y desencriptar y de tener el Cloud KMS. Es el ID de recurso de la clave necesario para usar CMEK. Para obtener información de cómo funcionan las CMEK con el Servicio de transferencia de datos de BigQuery, consulta Especifica la clave de encriptación con consultas programadas.

Permisos necesarios

Para programar una consulta, necesitas los siguientes permisos de IAM:

• Para crear la transferencia, debes tener los permisos bigquery.transfers.update y bigquery.datasets.get o los permisos bigquery.jobs.create, bigquery.transfers.get y bigquery.datasets.get.

  Nota: Si usas la consola de Google Cloud o la herramienta de línea de comandos de bq para programar una consulta, debes tener el permiso bigquery.transfers.get.

• Para ejecutar una consulta programada, debes tener lo siguiente:

  • Los permisos bigquery.datasets.get en el conjunto de datos de destino
  • bigquery.jobs.create

Para modificar o borrar una consulta programada, necesitas uno de los siguientes permisos de IAM:

• bigquery.transfers.update
• bigquery.jobs.create y propiedad sobre la consulta programada

La función predefinida de IAM roles/bigquery.admin incluye los permisos que necesitas para programar o modificar una consulta.

Para obtener más información de los roles de IAM en BigQuery, consulta Funciones y permisos predefinidos.

Para crear o actualizar consultas programadas que ejecuta una cuenta de servicio, debes tener acceso a esa cuenta. Si quieres más información para otorgarles a los usuarios el rol de cuenta de servicio, consulta Rol de usuario de cuenta de servicio. Para seleccionar una cuenta de servicio en la IU de consulta programada de la consola de Google Cloud, necesitas los siguientes permisos de IAM:

• iam.serviceAccounts.list

Nota: Si usas la herramienta de línea de comandos de bq, usa la marca --service_account_name en lugar de autenticarte como una cuenta de servicio.

Opciones de configuración

String de consulta

La string de consulta debe ser válida y estar escrita en GoogleSQL. Cada ejecución de una consulta programada puede recibir los siguientes parámetros de consulta.

Antes de programar una consulta, usa la herramienta de línea de comandos de bq para probar una cadena de consulta de forma manual con los parámetros @run_time y @run_date.

Parámetros disponibles

Parámetro	Tipo de GoogleSQL	Valor
@run_time	TIMESTAMP	Representado en la hora UTC. Para las consultas programadas con regularidad, run_time representa el tiempo previsto de ejecución. Por ejemplo, si la consulta programada tiene la configuración “cada 24 horas”, la diferencia de run_time entre dos consultas consecutivas será de 24 horas exactas, aunque el tiempo de ejecución real pueda variar un poco.
@run_date	DATE	Representa una fecha lógica del calendario.

Ejemplo

El parámetro @run_time es parte de la string de consulta en este ejemplo, que realiza una consulta a un conjunto de datos públicos llamado hacker_news.stories.

SELECT @run_time AS time,
  title,
  author,
  text
FROM `bigquery-public-data.hacker_news.stories`
LIMIT
  1000

Tabla de destino

Si la tabla de destino con tus resultados no existe cuando configuras la consulta programada, BigQuery intenta crear la tabla por ti.

Si usas una consulta DDL o DML, en la consola de Google Cloud, elige la región o la Ubicación de procesamiento. La ubicación de procesamiento se requiere en consultas DDL o DML que crean la tabla de destino.

Si la tabla de destino existe y usas la preferencia de escritura WRITE_APPEND, BigQuery agrega datos a la tabla de destino y, luego, intenta asignar el esquema. BigQuery permite automáticamente el agregado y el reordenamiento de campos, y admite los campos opcionales faltantes. Si el esquema de la tabla cambia tanto entre ejecuciones que BigQuery no puede procesar los cambios automáticamente, la consulta programada falla.

Las consultas pueden hacer referencia a tablas de diferentes proyectos y conjuntos de datos. Cuando configuras tu consulta programada, no necesitas incluir el conjunto de datos de destino en el nombre de la tabla. Debes especificar el conjunto de datos de destino por separado.

El conjunto de datos y la tabla de destino para una consulta programada deben estar en el mismo proyecto que la consulta programada.

Preferencia de escritura

La preferencia de escritura que selecciones determina cómo se escriben los resultados de tu consulta en una tabla de destino existente.

• WRITE_TRUNCATE: Si la tabla ya existe, BigQuery reemplaza los datos de la tabla.
• WRITE_APPEND: Si la tabla ya existe, BigQuery adjunta los datos a la tabla.

Si usas una consulta DDL o DML, no puedes usar la opción de preferencia de escritura.

Solo se crea, trunca o adjunta una tabla de destino si BigQuery puede completar la consulta con éxito. Las acciones de creación, truncamiento o adjuntado se producen como una actualización atómica cuando finaliza el trabajo.

Agrupamiento en clústeres

Con las consultas programadas, se puede crear agrupamiento en clústeres solo en tablas nuevas, si estas se hacen con una declaración de DDL CREATE TABLE AS SELECT. Consulta Crea una tabla agrupada en clústeres a partir del resultado de una consulta en la página Cómo usar instrucciones del lenguaje de definición de datos.

Opciones de partición

Las consultas programadas pueden crear tablas de destino particionadas o no particionadas. La partición está disponible en la consola de Google Cloud, la herramienta de línea de comandos de bq y los métodos de configuración de la API. Si usas una consulta DDL o DML con partición, deja el Campo de partición de la tabla de destino en blanco.

Puedes usar los siguientes tipos de partición de tablas en BigQuery:

• Partición de rango entero: Tablas particionadas según rangos de valores en una columna INTEGER específica.
• Partición de columnas de unidad de tiempo: Tablas particionadas basadas en un TIMESTAMP, DATE o la columna DATETIME.
• Partición por tiempo de transferencia: Tablas particionadas por tiempo de transferencia. BigQuery asigna filas automáticamente a particiones según la hora en que BigQuery transfiere los datos.

Para crear una tabla particionada con una consulta programada en la consola de Google Cloud, usa las siguientes opciones:

• Para usar la partición por rangos de números enteros, deja el Campo de partición de la tabla de destino en blanco.

• Para usar la partición de columna de unidad de tiempo, especifica el nombre de la columna en el Campo de partición de la tabla de destino cuando configures una consulta programada.

• Para usar la partición por tiempo de transferencia, deja el Campo de partición de la tabla de destino en blanco y, luego, indica la partición por fecha en el nombre de la tabla de destino. Por ejemplo, mytable${run_date} Para obtener más información, consulta Sintaxis de plantillas de parámetros.

Parámetros disponibles

Cuando configuras la consulta programada, puedes especificar cómo deseas particionar la tabla de destino con los parámetros de tiempo de ejecución.

Parámetro	Tipo de plantilla	Valor
run_time	Marca de tiempo con formato	En hora UTC, según el programa. Para las consultas programadas con regularidad, run_time representa el tiempo previsto de ejecución. Por ejemplo, si la consulta programada tiene la configuración “cada 24 horas”, la diferencia de run_time entre dos consultas consecutivas será de 24 horas exactas, aunque el tiempo de ejecución real pueda variar un poco. Consulta TransferRun.runTime.
run_date	String de fecha	La fecha del parámetro run_time tiene el siguiente formato: %Y-%m-%d; por ejemplo, 2018-01-01. Este formato es compatible con tablas particionadas por tiempo de transferencia.

Sistema de plantillas

Las consultas programadas admiten parámetros de tiempo de ejecución en el nombre de la tabla de destino con una sintaxis de plantilla.

Sintaxis de plantillas de parámetros

La sintaxis de plantillas admite plantillas de string y compensación horaria simples. Los parámetros se referencian en los siguientes formatos:

• {run_date}
• {run_time[+\-offset]|"time_format"}

Parámetro	Purpose
run_date	A este parámetro lo reemplaza la fecha en formato YYYYMMDD.
run_time	Este parámetro admite las siguientes propiedades: offset Compensación horaria expresada en horas (h), minutos (m) y segundos (s), en ese orden. Los días (d) no son compatibles. Se permiten decimales, por ejemplo, 1.5h. time_format Una string de formato. Los parámetros de formato más comunes son los años (%Y), los meses (%m), y los días (%d). En las tablas particionadas, YYYYMMDD es el sufijo obligatorio, equivalente a “%Y%m%d”. Obtén más información del formato de elementos de fecha y hora.

Notas de uso:

• No se permiten espacios en blanco entre run_time, la compensación horaria y el formato de hora.
• Para incluir llaves literales en la string, puedes marcarlas como '\{' and '\}'.
• Para incluir comillas textuales o una barra vertical en time_format, como "YYYY|MM|DD", puedes escaparlas en la string de formato como '\"' o '\|'.

Ejemplos de plantillas de parámetros

Estos ejemplos demuestran la especificación de nombres de tablas de destino con diferentes formatos de hora y compensación del tiempo de ejecución.

run_time (UTC)	Parámetro con plantilla	Nombre de la tabla de destino de salida
2018-02-15 00:00:00	mytable	mytable
2018-02-15 00:00:00	mytable_{run_time|"%Y%m%d"}	mytable_20180215
2018-02-15 00:00:00	mytable_{run_time+25h|"%Y%m%d"}	mytable_20180216
2018-02-15 00:00:00	mytable_{run_time-1h|"%Y%m%d"}	mytable_20180214
2018-02-15 00:00:00	mytable_{run_time+1.5h|"%Y%m%d%H"} o mytable_{run_time+90m|"%Y%m%d%H"}	mytable_2018021501
2018-02-15 00:00:00	{run_time+97s|"%Y%m%d"}_mytable_{run_time+97s|"%H%M%S"}	20180215_mytable_000137

Usa una cuenta de servicio

Puedes configurar una consulta programada para autenticar como una cuenta de servicio. Una cuenta de servicio es una Cuenta de Google asociada con tu proyecto de Google Cloud. La cuenta de servicio puede ejecutar trabajos, como consultas programadas o canalizaciones de procesamiento por lotes, con sus propias credenciales de servicio, en lugar de las credenciales de un usuario final.

Obtén más información de cómo autenticar con cuentas de servicio en Introducción a la autenticación.

• Puedes configurar la consulta programada con una cuenta de servicio. Si accediste con una identidad federada, se requiere una cuenta de servicio para crear una transferencia. Si accediste con una Cuenta de Google, la cuenta de servicio para dicha transferencia es opcional.

• Puedes actualizar una consulta programada existente con las credenciales de una cuenta de servicio con la herramienta de línea de comandos de bq o la consola de Google Cloud. Para obtener más información, consulta Actualiza las credenciales de consultas programadas.

Usa consultas programadas para especificar la clave de encriptación

Puedes especificar claves de encriptación administradas por el cliente (CMEKs) para encriptar los datos de una ejecución de transferencia. Puedes usar una CMEK para admitir transferencias de consultas programadas.

Cuando especificas una CMEK con una transferencia, el Servicio de transferencia de datos de BigQuery aplica la CMEK a cualquier memoria caché del disco intermedia de datos transferidos para que todo el flujo de trabajo de transferencia de datos cumpla con la CMEK.

No puedes actualizar una transferencia existente para agregar una CMEK si la transferencia no se creó en un principio con una CMEK. Por ejemplo, no puedes cambiar una tabla de destino que se encriptó de forma predeterminada para que ahora se encripte con CMEK. Por el contrario, tampoco puedes cambiar una tabla de destino encriptada con CMEK para que tenga un tipo de encriptación diferente.

Puedes actualizar una CMEK para una transferencia si la configuración de la transferencia se creó en un principio con una encriptación de CMEK. Cuando actualizas una CMEK para una configuración de transferencia, el Servicio de transferencia de datos de BigQuery propaga la CMEK a las tablas de destino en la siguiente ejecución de la transferencia, en la que el Servicio de transferencia de datos de BigQuery reemplaza cualquier CMEK desactualizada por la CMEK nueva durante la ejecución de la transferencia. Para obtener más información, consulta Actualiza una transferencia.

También puedes usar las claves predeterminadas del proyecto. Cuando especificas una clave predeterminada de proyecto con una transferencia, el Servicio de transferencia de datos de BigQuery usa la clave predeterminada del proyecto como la clave predeterminada para cualquier configuración de transferencia nueva.

Configura consultas programadas

Para obtener una descripción de la sintaxis del programa, consulta Define el formato de programa. Para obtener detalles sobre la sintaxis de programación, consulta Recurso: TransferConfig.

Console

1. Abre la página BigQuery en la consola de Google Cloud.

   Ir a BigQuery

2. Ejecuta la consulta que te interesa. Cuando estés conforme con los resultados, haz clic en Programar.

   

3. Las opciones de consulta programada se abren en el panel Nueva consulta programada (New scheduled query).

   

4. En el panel New scheduled query (Nueva consulta programada), ten en cuenta lo siguiente:

   • En Name for the scheduled query, ingresa un nombre como My scheduled query. El nombre de la consulta programada puede ser cualquier valor que puedas identificar más adelante si necesitas modificar la consulta.

   • Opcional: De forma predeterminada, la consulta está programada para ejecutarse Todos los días. Para cambiar el programa predeterminado, selecciona una opción del menú desplegable Se repite (Repeats):

     • Para especificar una frecuencia personalizada, selecciona Personalizada (Custom) y, luego, ingresa una especificación de tiempo similar a Cron en el campo Programación personalizada (Custom schedule); por ejemplo every mon 23:30 o every 6 hours. Para obtener más detalles sobre los programas válidos, incluidos los intervalos personalizados, consulta el campo schedule en Recurso: TransferConfig.

       

       Nota: La duración mínima entre las consultas programadas es de 5 minutos.

     • Para cambiar la hora de inicio, selecciona la opción Comenzar a la hora definida , ingresa la fecha y hora de inicio deseadas.

       Nota: Si la hora de inicio especificada es posterior a la hora del programa, la primera ejecución de la consulta será en la siguiente iteración del ciclo. Por ejemplo, una consulta creada a las 2022-06-05 23:50 con la programación daily 00:00 y la hora de inicio 2022-06-06 10:00 no se ejecutará hasta las 2022-06-07 00:00.

     • Para especificar una hora de finalización, selecciona la opción Programar una hora de finalización y, luego, ingresa la fecha y la hora de finalización deseadas.

     • Para guardar la consulta sin una programación, de modo que puedas ejecutarla a pedido más adelante, selecciona A pedido en el menú Repeticiones.

5. Para una consulta SELECT de GoogleSQL, selecciona la opción Set a destination table for query results (Establece una tabla de destino para los resultados de la consulta) y proporciona la siguiente información del conjunto de datos de destino.

   • En Dataset name (Nombre del conjunto de datos), elige el conjunto de datos de destino apropiado.
   • En Nombre de tabla (Table name), ingresa el nombre de tu tabla de destino.

   • En Destination table write preference (Preferencia de escritura de tabla de destino), selecciona Append to table (Agregar a la tabla) para agregar los datos a la tabla o Overwrite table (Reemplazar tabla) en lugar de tabla de destino.

     

6. Elige el Tipo de ubicación.

   • Si habilitaste la tabla de destino para los resultados de la consulta, puedes seleccionar Selección automática de ubicación para seleccionar automáticamente la ubicación en la que reside la tabla de destino.

   • De lo contrario, elige la ubicación en la que se encuentran los datos que se consultan.

7. Opciones avanzadas:

   • Opcional: CMEK Si usas claves de encriptación administradas por el cliente, puedes seleccionar Clave administrada por el cliente en Opciones avanzadas. Aparecerá una lista de las CMEK disponibles para que elijas. Para obtener información de cómo funcionan las claves de encriptación administradas por el cliente (CMEK) con el Servicio de transferencia de datos de BigQuery, consulta Especifica la clave de encriptación con consultas programadas.

   • Autentícate como una cuenta de servicio. Si tienes una o más cuentas de servicio asociadas a tu proyecto de Google Cloud, puedes asociar una cuenta de servicio con tu consulta programada en vez de usar tus credenciales de usuario. En Credencial de consulta programada (Scheduled query credential), haz clic en el menú para ver una lista de las cuentas de servicio que tienes disponibles. Si accediste como una identidad federada, se requiere una cuenta de servicio.

     

8. Configuraciones adicionales:

   • Opcional: Marca Enviar notificaciones por correo electrónico para activar las notificaciones por correo electrónico de las ejecuciones de transferencia con errores.

   • Opcional: En Tema de Pub/Sub, ingresa el nombre de tu tema de Pub/Sub, por ejemplo, projects/myproject/topics/mytopic.

     

9. Haz clic en Guardar.

bq

Existen dos formas de programar una consulta con la herramienta de línea de comandos de bq. Con la Opción 2, puedes programar la consulta con más opciones.

Opción 1: Usa el comando bq query.

Para crear una consulta programada, agrega las opciones destination_table (o target_dataset), --schedule y --display_name a tu comando bq query.

bq query \
--display_name=name \
--destination_table=table \
--schedule=interval

Reemplaza lo siguiente:

• name. El nombre visible de la consulta programada. El nombre visible puede ser cualquier valor que puedas identificar más adelante si necesitas modificar la consulta.
• table. La tabla de destino para los resultados de la consulta.
  • --target_dataset es una forma alternativa de asignar un nombre al conjunto de datos de destino para los resultados de la consulta cuando se usa con consultas DDL y DML.
  • Usa --destination_table o --target_dataset, pero no ambas opciones.
• interval. Cuando se usa con bq query, convierte una consulta en una consulta programada recurrente. Es necesario tener un programa con la frecuencia con la que se debe ejecutar la consulta. Para obtener más detalles sobre los programas válidos, incluidos los intervalos personalizados, consulta el campo schedule en Recurso: TransferConfig. Ejemplos:
  • --schedule='every 24 hours'
  • --schedule='every 3 hours'
  • --schedule='every monday 09:00'
  • --schedule='1st sunday of sep,oct,nov 00:00'

Marcas opcionales:

• --project_id es el ID del proyecto. Si no se especifica --project_id, se usa el proyecto predeterminado.

• --replace reemplaza la tabla de destino con los resultados de la consulta después de cada ejecución de la consulta programada. Se borrarán los datos existentes. En el caso de las tablas no particionadas, también se borra el esquema.

• --append_table adjunta resultados a la tabla de destino.

• En las consultas de DDL y DML, también puedes proporcionar la marca --location para indicar una región específica de procesamiento. Si no se especifica --location, se usa la ubicación más cercana de Google Cloud.

Si no se especifican “--replace” ni “--append_table” cuando se programa la consulta, no se establece ninguna preferencia de escritura. Según la consulta, esto podría generar un error en las ejecuciones programadas posteriores.

Por ejemplo, con el siguiente comando, se crea una consulta programada llamada My Scheduled Query con la consulta simple SELECT 1 from mydataset.test. La tabla de destino es mytable en el conjunto de datos mydataset. La consulta programada se crea en el proyecto predeterminado de la siguiente manera:

    bq query \
    --use_legacy_sql=false \
    --destination_table=mydataset.mytable \
    --display_name='My Scheduled Query' \
    --schedule='every 24 hours' \
    --replace=true \
    'SELECT
      1
    FROM
      mydataset.test'

Opción 2: Usa el comando bq mk.

Las consultas programadas son un tipo de transferencia. Si quieres programar una consulta, puedes usar la herramienta de línea de comandos de bq para realizar una configuración de transferencia.

Las consultas deben estar en dialecto de SQL estándar para poder programarlas.

Ingresa el comando bq mk y proporciona las siguientes marcas obligatorias:

• --transfer_config
• --data_source
• --target_dataset (opcional para consultas DDL y DML)
• --display_name
• --params

Marcas opcionales:

• --project_id es el ID del proyecto. Si no se especifica --project_id, se usa el proyecto predeterminado.

• --schedule indica con qué frecuencia quieres que se ejecute la consulta. Si no se especifica --schedule, el valor predeterminado es “cada 24 horas”, según la hora de creación.

• En las consultas de DDL y DML, también puedes proporcionar la marca --location para indicar una región específica de procesamiento. Si no se especifica --location, se usa la ubicación más cercana de Google Cloud.

• --service_account_name es para autenticar tu consulta programada con una cuenta de servicio en lugar de tu cuenta de usuario individual.

• --destination_kms_key: Especifica el ID de recurso de la clave para la clave de Cloud KMS si usas una clave de encriptación administrada por el cliente (CMEK) para esta transferencia. Para obtener información de cómo funcionan las CMEK con el Servicio de transferencia de datos de BigQuery, consulta Especifica la clave de encriptación con consultas programadas.

bq mk \
--transfer_config \
--target_dataset=dataset \
--display_name=name \
--params='parameters' \
--data_source=data_source

Reemplaza lo siguiente:

• dataset. El conjunto de datos de destino para la configuración de transferencia.
  • Este parámetro es opcional para las consultas de DDL y DML. Se requiere para todas las demás consultas.
• name. El nombre visible de la configuración de transferencia. El nombre visible puede ser cualquier valor que puedas identificar más adelante si necesitas modificar la consulta.
• parameters. Contiene los parámetros para la configuración de la transferencia creada en formato JSON. Por ejemplo: --params='{"param":"param_value"}'
  • Para una consulta programada, debes proporcionar el parámetro query.
  • El parámetro destination_table_name_template es el nombre de tu tabla de destino.
    • Este parámetro es opcional para las consultas de DDL y DML. Se requiere para todas las demás consultas.
  • En el parámetro write_disposition, puedes elegir WRITE_TRUNCATE para truncar (reemplazar) la tabla de destino o WRITE_APPEND si quieres adjuntar los resultados de la consulta a la tabla de destino.
    • Este parámetro es opcional para las consultas de DDL y DML. Se requiere para todas las demás consultas.
• data_source. La fuente de datos: scheduled_query.
• Opcional: La marca --service_account_name es para autenticar con una cuenta de servicio en lugar de una cuenta de usuario individual.
• Opcional: El --destination_kms_key especifica el ID de recurso de la clave para la clave de Cloud KMS, por ejemplo, projects/project_name/locations/us/keyRings/key_ring_name/cryptoKeys/key_name.

Nota: Para escribir resultados en una tabla particionada por tiempo de transferencia, consulta las instrucciones en Tabla de destino. Una consulta programada falla si creas una configuración de transferencia con el parámetro destination_table_name_template configurado como una tabla particionada por tiempo de transferencia. También se muestra un error si configuras el parámetro partitioning_field como una tabla particionada por tiempo de transferencia.

Nota: No puedes configurar las notificaciones con la herramienta de línea de comandos.

Por ejemplo, el siguiente comando crea una configuración de transferencia de consulta programada con el nombre My Scheduled Query con la consulta simple SELECT 1 from mydataset.test. La tabla de destino mytable se trunca para cada escritura, y el conjunto de datos de destino es mydataset. La consulta programada se crea en el proyecto predeterminado y se autentica como una cuenta de servicio:

bq mk \
--transfer_config \
--target_dataset=mydataset \
--display_name='My Scheduled Query' \
--params='{"query":"SELECT 1 from mydataset.test","destination_table_name_template":"mytable","write_disposition":"WRITE_TRUNCATE"}' \
--data_source=scheduled_query \
--service_account_name=[e-mail]

La primera vez que ejecutes el comando, recibirás un mensaje similar al siguiente:

[URL omitted] Please copy and paste the above URL into your web browser and follow the instructions to retrieve an authentication code.

Sigue las instrucciones del mensaje y pega el código de autenticación en la línea de comandos.

API

Usa el método projects.locations.transferConfigs.create y proporciona una instancia del recurso TransferConfig.

Java

Para aprender a instalar y usar la biblioteca cliente de BigQuery, consulta las bibliotecas cliente de BigQuery. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Java.

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.

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.CreateTransferConfigRequest;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.ProjectName;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.protobuf.Struct;
import com.google.protobuf.Value;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

// Sample to create a scheduled query
public class CreateScheduledQuery {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "MY_PROJECT_ID";
    final String datasetId = "MY_DATASET_ID";
    final String query =
        "SELECT CURRENT_TIMESTAMP() as current_time, @run_time as intended_run_time, "
            + "@run_date as intended_run_date, 17 as some_integer";
    Map<String, Value> params = new HashMap<>();
    params.put("query", Value.newBuilder().setStringValue(query).build());
    params.put(
        "destination_table_name_template",
        Value.newBuilder().setStringValue("my_destination_table_{run_date}").build());
    params.put("write_disposition", Value.newBuilder().setStringValue("WRITE_TRUNCATE").build());
    params.put("partitioning_field", Value.newBuilder().build());
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setDestinationDatasetId(datasetId)
            .setDisplayName("Your Scheduled Query Name")
            .setDataSourceId("scheduled_query")
            .setParams(Struct.newBuilder().putAllFields(params).build())
            .setSchedule("every 24 hours")
            .build();
    createScheduledQuery(projectId, transferConfig);
  }

  public static void createScheduledQuery(String projectId, TransferConfig transferConfig)
      throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      ProjectName parent = ProjectName.of(projectId);
      CreateTransferConfigRequest request =
          CreateTransferConfigRequest.newBuilder()
              .setParent(parent.toString())
              .setTransferConfig(transferConfig)
              .build();
      TransferConfig config = dataTransferServiceClient.createTransferConfig(request);
      System.out.println("\nScheduled query created successfully :" + config.getName());
    } catch (ApiException ex) {
      System.out.print("\nScheduled query was not created." + ex.toString());
    }
  }
}

Python

Para aprender a instalar y usar la biblioteca cliente de BigQuery, consulta las bibliotecas cliente de BigQuery. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Python.

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.

from google.cloud import bigquery_datatransfer

transfer_client = bigquery_datatransfer.DataTransferServiceClient()

# The project where the query job runs is the same as the project
# containing the destination dataset.
project_id = "your-project-id"
dataset_id = "your_dataset_id"

# This service account will be used to execute the scheduled queries. Omit
# this request parameter to run the query as the user with the credentials
# associated with this client.
service_account_name = "[e-mail]"

# Use standard SQL syntax for the query.
query_string = """
SELECT
  CURRENT_TIMESTAMP() as current_time,
  @run_time as intended_run_time,
  @run_date as intended_run_date,
  17 as some_integer
"""

parent = transfer_client.common_project_path(project_id)

transfer_config = bigquery_datatransfer.TransferConfig(
    destination_dataset_id=dataset_id,
    display_name="Your Scheduled Query Name",
    data_source_id="scheduled_query",
    params={
        "query": query_string,
        "destination_table_name_template": "your_table_{run_date}",
        "write_disposition": "WRITE_TRUNCATE",
        "partitioning_field": "",
    },
    schedule="every 24 hours",
)

transfer_config = transfer_client.create_transfer_config(
    bigquery_datatransfer.CreateTransferConfigRequest(
        parent=parent,
        transfer_config=transfer_config,
        service_account_name=service_account_name,
    )
)

print("Created scheduled query '{}'".format(transfer_config.name))

Configura consultas programadas con una cuenta de servicio

Java

Para aprender a instalar y usar la biblioteca cliente de BigQuery, consulta las bibliotecas cliente de BigQuery. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Java.

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.

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.CreateTransferConfigRequest;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.ProjectName;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.protobuf.Struct;
import com.google.protobuf.Value;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

// Sample to create a scheduled query with service account
public class CreateScheduledQueryWithServiceAccount {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "MY_PROJECT_ID";
    final String datasetId = "MY_DATASET_ID";
    final String serviceAccount = "MY_SERVICE_ACCOUNT";
    final String query =
        "SELECT CURRENT_TIMESTAMP() as current_time, @run_time as intended_run_time, "
            + "@run_date as intended_run_date, 17 as some_integer";
    Map<String, Value> params = new HashMap<>();
    params.put("query", Value.newBuilder().setStringValue(query).build());
    params.put(
        "destination_table_name_template",
        Value.newBuilder().setStringValue("my_destination_table_{run_date}").build());
    params.put("write_disposition", Value.newBuilder().setStringValue("WRITE_TRUNCATE").build());
    params.put("partitioning_field", Value.newBuilder().build());
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setDestinationDatasetId(datasetId)
            .setDisplayName("Your Scheduled Query Name")
            .setDataSourceId("scheduled_query")
            .setParams(Struct.newBuilder().putAllFields(params).build())
            .setSchedule("every 24 hours")
            .build();
    createScheduledQueryWithServiceAccount(projectId, transferConfig, serviceAccount);
  }

  public static void createScheduledQueryWithServiceAccount(
      String projectId, TransferConfig transferConfig, String serviceAccount) throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      ProjectName parent = ProjectName.of(projectId);
      CreateTransferConfigRequest request =
          CreateTransferConfigRequest.newBuilder()
              .setParent(parent.toString())
              .setTransferConfig(transferConfig)
              .setServiceAccountName(serviceAccount)
              .build();
      TransferConfig config = dataTransferServiceClient.createTransferConfig(request);
      System.out.println(
          "\nScheduled query with service account created successfully :" + config.getName());
    } catch (ApiException ex) {
      System.out.print("\nScheduled query with service account was not created." + ex.toString());
    }
  }
}

Python

Para aprender a instalar y usar la biblioteca cliente de BigQuery, consulta las bibliotecas cliente de BigQuery. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Python.

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.

from google.cloud import bigquery_datatransfer

transfer_client = bigquery_datatransfer.DataTransferServiceClient()

# The project where the query job runs is the same as the project
# containing the destination dataset.
project_id = "your-project-id"
dataset_id = "your_dataset_id"

# This service account will be used to execute the scheduled queries. Omit
# this request parameter to run the query as the user with the credentials
# associated with this client.
service_account_name = "[e-mail]"

# Use standard SQL syntax for the query.
query_string = """
SELECT
  CURRENT_TIMESTAMP() as current_time,
  @run_time as intended_run_time,
  @run_date as intended_run_date,
  17 as some_integer
"""

parent = transfer_client.common_project_path(project_id)

transfer_config = bigquery_datatransfer.TransferConfig(
    destination_dataset_id=dataset_id,
    display_name="Your Scheduled Query Name",
    data_source_id="scheduled_query",
    params={
        "query": query_string,
        "destination_table_name_template": "your_table_{run_date}",
        "write_disposition": "WRITE_TRUNCATE",
        "partitioning_field": "",
    },
    schedule="every 24 hours",
)

transfer_config = transfer_client.create_transfer_config(
    bigquery_datatransfer.CreateTransferConfigRequest(
        parent=parent,
        transfer_config=transfer_config,
        service_account_name=service_account_name,
    )
)

print("Created scheduled query '{}'".format(transfer_config.name))

Visualiza el estado de la consulta programada

Console

Para ver el estado de tus consultas programadas, haz clic en Scheduled queries (Consultas programadas) en el panel de navegación. Actualiza la página para ver el estado actualizado de tus consultas programadas. Haz clic en una consulta programada para obtener más detalles sobre ella.

bq

Las consultas programadas son un tipo de transferencia. Para mostrar los detalles de una consulta programada, primero puedes usar la herramienta de línea de comandos de bq para hacer una lista de las opciones de configuración de transferencia.

Ingresa el comando bq ls y proporciona la marca de transferencia --transfer_config. También se requieren las siguientes marcas:

• --transfer_location

Por ejemplo:

bq ls \
--transfer_config \
--transfer_location=us

Para que se muestren los detalles de una sola consulta programada, ingresa el comando bq show y proporciona transfer_path de esa consulta programada o configuración de transferencia.

Por ejemplo:

bq show \
--transfer_config \
projects/862514376110/locations/us/transferConfigs/5dd12f26-0000-262f-bc38-089e0820fe38

API

Usa el método projects.locations.transferConfigs.list y proporciona una instancia del recurso TransferConfig.

Java

Para aprender a instalar y usar la biblioteca cliente de BigQuery, consulta las bibliotecas cliente de BigQuery. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Java.

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.

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.ListTransferConfigsRequest;
import com.google.cloud.bigquery.datatransfer.v1.ProjectName;
import java.io.IOException;

// Sample to get list of transfer config
public class ListTransferConfigs {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "MY_PROJECT_ID";
    listTransferConfigs(projectId);
  }

  public static void listTransferConfigs(String projectId) throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      ProjectName parent = ProjectName.of(projectId);
      ListTransferConfigsRequest request =
          ListTransferConfigsRequest.newBuilder().setParent(parent.toString()).build();
      dataTransferServiceClient
          .listTransferConfigs(request)
          .iterateAll()
          .forEach(config -> System.out.print("Success! Config ID :" + config.getName() + "\n"));
    } catch (ApiException ex) {
      System.out.println("Config list not found due to error." + ex.toString());
    }
  }
}

Python

Para aprender a instalar y usar la biblioteca cliente de BigQuery, consulta las bibliotecas cliente de BigQuery. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Python.

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.

from google.cloud import bigquery_datatransfer

transfer_client = bigquery_datatransfer.DataTransferServiceClient()

project_id = "my-project"
parent = transfer_client.common_project_path(project_id)

configs = transfer_client.list_transfer_configs(parent=parent)
print("Got the following configs:")
for config in configs:
    print(f"\tID: {config.name}, Schedule: {config.schedule}")

Actualiza consultas programadas

Console

Para actualizar una consulta programada, sigue estos pasos:

1. En el panel de navegación, haz clic en Consultas programadas.
2. En la lista de consultas programadas, haz clic en el nombre de la consulta que deseas cambiar.
3. En la página Detalles de la consulta programada que se abre, haz clic en Editar.
4. Opcional: cambia el texto de la consulta en el panel de edición de consultas.
5. Haz clic en Programar consulta y, luego, selecciona Actualizar consulta programada.
6. Opcional: cambia cualquier otra opción de programación para la consulta.
7. Haz clic en Actualizar.

bq

Las consultas programadas son un tipo de transferencia. Para actualizar la consulta programada, puedes usar la herramienta de línea de comandos de bq para realizar una configuración de transferencia.

Ingresa el comando bq update con la marca --transfer_config requerida.

Marcas opcionales:

• --project_id es el ID del proyecto. Si no se especifica --project_id, se usa el proyecto predeterminado.

• --schedule indica con qué frecuencia quieres que se ejecute la consulta. Si no se especifica --schedule, el valor predeterminado es “cada 24 horas”, según la hora de creación.

• --service_account_name solo tiene efecto si también se configura --update_credentials. Para obtener más información, consulta Actualiza las credenciales de consultas programadas.

• --target_dataset (opcional para las consultas DDL y DML) es una forma alternativa de asignar un nombre al conjunto de datos de destino para los resultados de la consulta cuando se usa con consultas DDL y DML.

• --display_name es el nombre de la consulta programada.

• --params son los parámetros de la configuración de transferencia creada en formato JSON. Por ejemplo: --params='{"param":"param_value"}'.

• --destination_kms_key: Especifica el ID de recurso de la clave para la clave de Cloud KMS si usas una clave de encriptación administrada por el cliente (CMEK) para esta transferencia. Para obtener información de cómo funcionan las claves de encriptación administradas por el cliente (CMEK) con el Servicio de transferencia de datos de BigQuery, consulta Especifica la clave de encriptación con consultas programadas.

bq update \
--target_dataset=dataset \
--display_name=name \
--params='parameters'
--transfer_config \
RESOURCE_NAME

Reemplaza lo siguiente:

• dataset. El conjunto de datos de destino para la configuración de transferencia. Este parámetro es opcional para las consultas de DDL y DML. Se requiere para todas las demás consultas.
• name. El nombre visible de la configuración de transferencia. El nombre visible puede ser cualquier valor que puedas identificar más adelante si necesitas modificar la consulta.
• parameters. Contiene los parámetros para la configuración de la transferencia creada en formato JSON. Por ejemplo: --params='{"param":"param_value"}'
  • Para una consulta programada, debes proporcionar el parámetro query.
  • El parámetro destination_table_name_template es el nombre de tu tabla de destino. Este parámetro es opcional para las consultas de DDL y DML. Se requiere para todas las demás consultas.
  • En el parámetro write_disposition, puedes elegir WRITE_TRUNCATE para truncar (reemplazar) la tabla de destino o WRITE_APPEND si quieres adjuntar los resultados de la consulta a la tabla de destino. Este parámetro es opcional para las consultas de DDL y DML. Se requiere para todas las demás consultas.
• Opcional: El --destination_kms_key especifica el ID de recurso de la clave para la clave de Cloud KMS, por ejemplo, projects/project_name/locations/us/keyRings/key_ring_name/cryptoKeys/key_name.
• RESOURCE_NAME es el nombre del recurso de la transferencia (también conocido como la configuración de transferencia). Si no conoces el nombre del recurso de la transferencia, busca el nombre del recurso con: bq ls --transfer_config --transfer_location=location.

Nota: Para escribir resultados en una tabla particionada por tiempo de transferencia, consulta las instrucciones en Tabla de destino. Una consulta programada falla si creas una configuración de transferencia con el parámetro destination_table_name_template configurado como una tabla particionada por tiempo de transferencia. También se muestra un error si configuras el parámetro partitioning_field como una tabla particionada por tiempo de transferencia.

Nota: No puedes configurar las notificaciones con la herramienta de línea de comandos.

Por ejemplo, el siguiente comando actualiza una configuración de transferencia de consulta programada con el nombre My Scheduled Query con la consulta simple SELECT 1 from mydataset.test. La tabla de destino mytable se trunca para cada operación de escritura, y el conjunto de datos de destino es mydataset:

bq update \
--target_dataset=mydataset \
--display_name='My Scheduled Query' \
--params='{"query":"SELECT 1 from mydataset.test","destination_table_name_template":"mytable","write_disposition":"WRITE_TRUNCATE"}'
--transfer_config \
projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7

API

Usa el método projects.transferConfigs.patch y proporciona el nombre del recurso de la transferencia con el parámetro transferConfig.name. Si no conoces el nombre del recurso de la transferencia, ejecuta el comando bq ls --transfer_config --transfer_location=location para ver una lista de todas las transferencias o llama al método projects.locations.transferConfigs.list y proporciona el ID del proyecto con el parámetro parent.

Java

Para aprender a instalar y usar la biblioteca cliente de BigQuery, consulta las bibliotecas cliente de BigQuery. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Java.

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.

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.cloud.bigquery.datatransfer.v1.UpdateTransferConfigRequest;
import com.google.protobuf.FieldMask;
import com.google.protobuf.util.FieldMaskUtil;
import java.io.IOException;

// Sample to update transfer config.
public class UpdateTransferConfig {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String configId = "MY_CONFIG_ID";
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setName(configId)
            .setDisplayName("UPDATED_DISPLAY_NAME")
            .build();
    FieldMask updateMask = FieldMaskUtil.fromString("display_name");
    updateTransferConfig(transferConfig, updateMask);
  }

  public static void updateTransferConfig(TransferConfig transferConfig, FieldMask updateMask)
      throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      UpdateTransferConfigRequest request =
          UpdateTransferConfigRequest.newBuilder()
              .setTransferConfig(transferConfig)
              .setUpdateMask(updateMask)
              .build();
      TransferConfig updateConfig = dataTransferServiceClient.updateTransferConfig(request);
      System.out.println("Transfer config updated successfully :" + updateConfig.getDisplayName());
    } catch (ApiException ex) {
      System.out.print("Transfer config was not updated." + ex.toString());
    }
  }
}

Python

Para aprender a instalar y usar la biblioteca cliente de BigQuery, consulta las bibliotecas cliente de BigQuery. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Python.

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.

from google.cloud import bigquery_datatransfer
from google.protobuf import field_mask_pb2

transfer_client = bigquery_datatransfer.DataTransferServiceClient()

transfer_config_name = "projects/1234/locations/us/transferConfigs/abcd"
new_display_name = "My Transfer Config"

transfer_config = bigquery_datatransfer.TransferConfig(name=transfer_config_name)
transfer_config.display_name = new_display_name

transfer_config = transfer_client.update_transfer_config(
    {
        "transfer_config": transfer_config,
        "update_mask": field_mask_pb2.FieldMask(paths=["display_name"]),
    }
)

print(f"Updated config: '{transfer_config.name}'")
print(f"New display name: '{transfer_config.display_name}'")

Nota: No se puede actualizar la ubicación de una consulta programada. Si mueves un conjunto de datos de origen o de destino usado en una consulta programada, debes crear una consulta programada nueva en la ubicación nueva.

Actualiza las consultas programadas con restricciones de propiedad

Si intentas actualizar una consulta programada que no te pertenece, es posible que la actualización falle con el siguiente mensaje de error:

Cannot modify restricted parameters without taking ownership of the transfer configuration.

El propietario de la consulta programada es el usuario asociado a la consulta programada o el usuario que tiene acceso a la cuenta de servicio asociada con la consulta programada. El usuario asociado se puede ver en los detalles de configuración de la consulta programada. Si deseas obtener información de cómo actualizar la consulta programada para que sea de su propiedad, consulta Actualiza las credenciales de consultas programadas. Para otorgar acceso a los usuarios a una cuenta de servicio, debes tener la función de usuario de cuenta de servicio.

Cualquier usuario que no sea el propietario de la consulta programada, pero que tenga acceso a todos los recursos mencionados en la consulta, es posible que se le permita actualizar la consulta. Esta situación solo se admite si la consulta se puede validar en un minuto o dos. De lo contrario, recibirás el mismo mensaje de error que se mencionó antes. Si la consulta es demasiado compleja, puedes actualizar las credenciales de la consulta programada para tomar la propiedad directa de la consulta programada o usar una cuenta de servicio.

Actualiza las credenciales de consultas programadas

Si programas una consulta existente, es posible que debas actualizar las credenciales del usuario en la consulta. Las credenciales se actualizan automáticamente para las nuevas consultas programadas.

A continuación, se presentan algunas situaciones que podrían requerir la actualización de credenciales:

• Deseas consultar los datos de Google Drive en una consulta programada.

• Recibes un error INVALID_USER cuando intentas programar la consulta:

  Error code 5 : Authentication failure: User Id not found. Error code: INVALID_USERID

• Recibirás el siguiente error de parámetros restringidos cuando intentes actualizar la consulta:

  Cannot modify restricted parameters without taking ownership of the transfer configuration.

Nota: Si no eres el propietario de la consulta de programación, debes tener el permiso bigquery.transfers.update en tu proyecto de Google Cloud para actualizar las credenciales de la consulta programada. Para obtener más información, consulta Permisos necesarios.

Console

Sigue estos pasos para actualizar las credenciales existentes en una consulta programada:

1. Busca y consulta el estado de una consulta programada.

2. Haz clic en el botón MORE (MÁS) y selecciona Update credentials (Actualizar credenciales).

   

3. Espera entre 10 y 20 minutos para que se aplique el cambio. Es posible que debas borrar la caché de tu navegador.

Advertencia: En la consola de Google Cloud, no se admite el cambio de credenciales que se usaron en una consulta programada a una cuenta de servicio.

bq

Las consultas programadas son un tipo de transferencia. Para actualizar las credenciales de una consulta programada, puedes usar la herramienta de línea de comandos de bq para actualizar la configuración de la transferencia.

Ingresa el comando bq update y proporciona la marca de transferencia --transfer_config. También se requieren las siguientes marcas:

• --update_credentials

Marca opcional:

• --service_account_name es para autenticar tu consulta programada con una cuenta de servicio en lugar de tu cuenta de usuario individual.

Por ejemplo, el siguiente comando actualiza una configuración de transferencia de consulta programada para autenticar como una cuenta de servicio:

bq update \
--update_credentials \
--service_account_name=[e-mail]
--transfer_config \
projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7

Java

Para aprender a instalar y usar la biblioteca cliente de BigQuery, consulta las bibliotecas cliente de BigQuery. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Java.

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.

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.cloud.bigquery.datatransfer.v1.UpdateTransferConfigRequest;
import com.google.protobuf.FieldMask;
import com.google.protobuf.util.FieldMaskUtil;
import java.io.IOException;

// Sample to update credentials in transfer config.
public class UpdateCredentials {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String configId = "MY_CONFIG_ID";
    String serviceAccount = "MY_SERVICE_ACCOUNT";
    TransferConfig transferConfig = TransferConfig.newBuilder().setName(configId).build();
    FieldMask updateMask = FieldMaskUtil.fromString("service_account_name");
    updateCredentials(transferConfig, serviceAccount, updateMask);
  }

  public static void updateCredentials(
      TransferConfig transferConfig, String serviceAccount, FieldMask updateMask)
      throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      UpdateTransferConfigRequest request =
          UpdateTransferConfigRequest.newBuilder()
              .setTransferConfig(transferConfig)
              .setUpdateMask(updateMask)
              .setServiceAccountName(serviceAccount)
              .build();
      dataTransferServiceClient.updateTransferConfig(request);
      System.out.println("Credentials updated successfully");
    } catch (ApiException ex) {
      System.out.print("Credentials was not updated." + ex.toString());
    }
  }
}

Python

Para aprender a instalar y usar la biblioteca cliente de BigQuery, consulta las bibliotecas cliente de BigQuery. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Python.

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.

from google.cloud import bigquery_datatransfer
from google.protobuf import field_mask_pb2

transfer_client = bigquery_datatransfer.DataTransferServiceClient()

service_account_name = "[e-mail]"
transfer_config_name = "projects/1234/locations/us/transferConfigs/abcd"

transfer_config = bigquery_datatransfer.TransferConfig(name=transfer_config_name)

transfer_config = transfer_client.update_transfer_config(
    {
        "transfer_config": transfer_config,
        "update_mask": field_mask_pb2.FieldMask(paths=["service_account_name"]),
        "service_account_name": service_account_name,
    }
)

print("Updated config: '{}'".format(transfer_config.name))

Configura una ejecución manual en fechas históricas

Además de programar una consulta para que se ejecute en el futuro, también puedes activar ejecuciones inmediatas de forma manual. Sería necesario activar una ejecución inmediata si tu consulta usa el parámetro run_date y si hubo problemas durante una ejecución anterior.

Por ejemplo, todos los días a las 09:00, consultas una tabla de origen para las filas que coinciden con la fecha actual. Sin embargo, descubres que los datos no se agregaron a la tabla de origen durante los últimos tres días. En esta situación, puedes configurar la consulta para que se ejecute en función de datos históricos dentro de un período que especifiques. Tu consulta se ejecuta con combinaciones de los parámetros run_date y run_time que corresponden a las fechas que configuraste en la consulta programada.

Una vez configurada una consulta programada, puedes ejecutar la consulta con un período histórico de la siguiente manera:

Console

Después de hacer clic en Programar para guardar tu consulta programada, puedes hacer clic en el botón Consultas programadas para ver la lista de consultas programadas en el momento. Haz clic en cualquier nombre visible para ver los detalles del programa de la consulta. En la parte superior derecha de la página, haz clic en Programar reabastecimiento (Schedule backfill) para especificar un período histórico.

Los tiempos de ejecución seleccionados están todos dentro del rango seleccionado, incluida la primera fecha y excluida la última fecha.

Los períodos que proporcionas estarán en UTC, pero el programa de la consulta se muestra en tu zona horaria local (consulta el Ejemplo 2 para solucionar este problema).

Ejemplo 1

Tu consulta programada está configurada para ejecutarse every day 09:00 según la hora del Pacífico. Te faltan datos del 1, 2 y 3 de enero. Selecciona el siguiente período histórico:

Start Time = 1/1/19
End Time = 1/4/19

Tu consulta se ejecuta con los parámetros run_date y run_time, que corresponden a las siguientes fechas y horas:

• 1/1/19 09:00 a.m. hora del Pacífico
• 2/1/19 09:00 a.m. hora del Pacífico
• 3/1/19 09:00 a.m. hora del Pacífico

Ejemplo 2

Tu consulta programada está configurada para ejecutarse every day 23:00 según la hora del Pacífico. Te faltan datos del 1, 2 y 3 de enero. Selecciona los siguientes períodos históricos (se seleccionan fechas posteriores porque el estándar UTC tiene una fecha diferente a las 11:00 p.m. hora del Pacífico):

Start Time = 1/2/19
End Time = 1/5/19

Tu consulta se ejecuta con los parámetros run_date y run_time, que corresponden a las siguientes fechas y horas:

• 2/1/19 6:00 a.m. UTC o 1/1/2019 11:00 p.m. hora del Pacífico
• 3/1/19 6:00 a.m. UTC o 2/1/2019 11:00 p.m. hora del Pacífico
• 4/1/19 6:00 a.m UTC o 3/1/2019 11:00 p.m. hora del Pacífico

Después de configurar ejecuciones manuales, actualiza la página para verlas en la lista de ejecuciones.

bq

Para ejecutar la consulta de forma manual en un período histórico, haz lo siguiente:

Ingresa el comando bq mk y proporciona la marca de ejecución de transferencias --transfer_run. También se requieren las siguientes marcas:

• --start_time
• --end_time

bq mk \
--transfer_run \
--start_time='start_time' \
--end_time='end_time' \
resource_name

Reemplaza lo siguiente:

• start_time y end_time. Marcas de tiempo que terminan en Z o contienen un desplazamiento de zona horaria válido. Ejemplos:
  • 2017-08-19T12:11:35.00Z
  • 2017-05-25T00:00:00+00:00
• resource_name. El nombre del recurso de la consulta programada (o de la transferencia). El nombre del recurso también se conoce como la configuración de transferencia.

Por ejemplo, el siguiente comando programa un reabastecimiento para el recurso de consulta programada (o la configuración de transferencia): projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7.

  bq mk \
  --transfer_run \
  --start_time 2017-05-25T00:00:00Z \
  --end_time 2017-05-25T00:00:00Z \
  projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7

Para obtener más información, consulta bq mk --transfer_run.

API

Usa el método projects.locations.transferConfigs.scheduleRun y proporciona la ruta del recurso TransferConfig.

Java

Para aprender a instalar y usar la biblioteca cliente de BigQuery, consulta las bibliotecas cliente de BigQuery. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Java.

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.

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.ScheduleTransferRunsRequest;
import com.google.cloud.bigquery.datatransfer.v1.ScheduleTransferRunsResponse;
import com.google.protobuf.Timestamp;
import java.io.IOException;
import org.threeten.bp.Clock;
import org.threeten.bp.Instant;
import org.threeten.bp.temporal.ChronoUnit;

// Sample to run schedule back fill for transfer config
public class ScheduleBackFill {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String configId = "MY_CONFIG_ID";
    Clock clock = Clock.systemDefaultZone();
    Instant instant = clock.instant();
    Timestamp startTime =
        Timestamp.newBuilder()
            .setSeconds(instant.minus(5, ChronoUnit.DAYS).getEpochSecond())
            .setNanos(instant.minus(5, ChronoUnit.DAYS).getNano())
            .build();
    Timestamp endTime =
        Timestamp.newBuilder()
            .setSeconds(instant.minus(2, ChronoUnit.DAYS).getEpochSecond())
            .setNanos(instant.minus(2, ChronoUnit.DAYS).getNano())
            .build();
    scheduleBackFill(configId, startTime, endTime);
  }

  public static void scheduleBackFill(String configId, Timestamp startTime, Timestamp endTime)
      throws IOException {
    try (DataTransferServiceClient client = DataTransferServiceClient.create()) {
      ScheduleTransferRunsRequest request =
          ScheduleTransferRunsRequest.newBuilder()
              .setParent(configId)
              .setStartTime(startTime)
              .setEndTime(endTime)
              .build();
      ScheduleTransferRunsResponse response = client.scheduleTransferRuns(request);
      System.out.println("Schedule backfill run successfully :" + response.getRunsCount());
    } catch (ApiException ex) {
      System.out.print("Schedule backfill was not run." + ex.toString());
    }
  }
}

Python

Para aprender a instalar y usar la biblioteca cliente de BigQuery, consulta las bibliotecas cliente de BigQuery. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Python.

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.

import datetime

from google.cloud.bigquery_datatransfer_v1 import (
    DataTransferServiceClient,
    StartManualTransferRunsRequest,
)

# Create a client object
client = DataTransferServiceClient()

# Replace with your transfer configuration name
transfer_config_name = "projects/1234/locations/us/transferConfigs/abcd"
now = datetime.datetime.now(datetime.timezone.utc)
start_time = now - datetime.timedelta(days=5)
end_time = now - datetime.timedelta(days=2)

# Some data sources, such as scheduled_query only support daily run.
# Truncate start_time and end_time to midnight time (00:00AM UTC).
start_time = datetime.datetime(
    start_time.year, start_time.month, start_time.day, tzinfo=datetime.timezone.utc
)
end_time = datetime.datetime(
    end_time.year, end_time.month, end_time.day, tzinfo=datetime.timezone.utc
)

requested_time_range = StartManualTransferRunsRequest.TimeRange(
    start_time=start_time,
    end_time=end_time,
)

# Initialize request argument(s)
request = StartManualTransferRunsRequest(
    parent=transfer_config_name,
    requested_time_range=requested_time_range,
)

# Make the request
response = client.start_manual_transfer_runs(request=request)

# Handle the response
print("Started manual transfer runs:")
for run in response.runs:
    print(f"backfill: {run.run_time} run: {run.name}")

Borra consultas programadas

Console

Para borrar una consulta programada a través de la consola, haz lo siguiente:

1. En el panel de navegación, haz clic en Consultas programadas.

2. En la lista de consultas programadas, haz clic en el nombre de la consulta programada que deseas borrar.

3. En la página Detalles de la consulta programada que se abre, haz clic en Borrar.

Java

Para aprender a instalar y usar la biblioteca cliente de BigQuery, consulta las bibliotecas cliente de BigQuery. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Java.

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.

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.DeleteTransferConfigRequest;
import java.io.IOException;

// Sample to delete a transfer config
public class DeleteTransferConfig {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    // i.e projects/{project_id}/transferConfigs/{config_id}` or
    // `projects/{project_id}/locations/{location_id}/transferConfigs/{config_id}`
    String configId = "MY_CONFIG_ID";
    deleteTransferConfig(configId);
  }

  public static void deleteTransferConfig(String configId) throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      DeleteTransferConfigRequest request =
          DeleteTransferConfigRequest.newBuilder().setName(configId).build();
      dataTransferServiceClient.deleteTransferConfig(request);
      System.out.println("Transfer config deleted successfully");
    } catch (ApiException ex) {
      System.out.println("Transfer config was not deleted." + ex.toString());
    }
  }
}

Python

Para aprender a instalar y usar la biblioteca cliente de BigQuery, consulta las bibliotecas cliente de BigQuery. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Python.

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.

import google.api_core.exceptions
from google.cloud import bigquery_datatransfer

transfer_client = bigquery_datatransfer.DataTransferServiceClient()

transfer_config_name = "projects/1234/locations/us/transferConfigs/abcd"
try:
    transfer_client.delete_transfer_config(name=transfer_config_name)
except google.api_core.exceptions.NotFound:
    print("Transfer config not found.")
else:
    print(f"Deleted transfer config: {transfer_config_name}")

Cuotas

Las consultas programadas se ejecutan con las credenciales y el proyecto del creador, como si estuvieras ejecutando la consulta tú mismo. Las consultas programadas siempre se ejecutan como trabajos de consulta por lotes.

A pesar de que las consultas programadas usan funciones del Servicio de transferencia de datos de BigQuery, estas no son transferencias y no están sujetas a la cuota de los trabajos de carga. En cambio, están sujetas a las mismas cuotas y límites de BigQuery que las consultas manuales.

Precios

Las consultas programadas tienen el mismo precio que las consultas de BigQuery manuales.

Regiones admitidas

Precaución: No se admiten consultas entre regiones. La tabla de destino de la consulta programada debe estar en la misma región que los datos que se consultan. La ubicación seleccionada para la consulta programada también debe ser la misma región que los datos que se consultan.

Las consultas programadas se admiten en las siguientes ubicaciones.

Regiones

En la siguiente tabla, se enumeran las regiones de América en las que está disponible BigQuery.

Descripción de la región	Nombre de la región	Detalles
Columbus, Ohio	us-east5
Dallas	us-south1	CO2 bajo
Iowa	us-central1	CO2 bajo
Las Vegas	us-west4
Los Ángeles	us-west2
Montreal	northamerica-northeast1	CO2 bajo
Virginia del Norte	us-east4
Oregón	us-west1	CO2 bajo
Salt Lake City	us-west3
São Paulo	southamerica-east1	CO2 bajo
Santiago	southamerica-west1	CO2 bajo
Carolina del Sur	us-east1
Toronto	northamerica-northeast2	CO2 bajo

En la siguiente tabla, se muestran las regiones de Asia-Pacífico en las que está disponible BigQuery.

Descripción de la región	Nombre de la región	Detalles
Delhi	asia-south2
Hong Kong	asia-east2
Yakarta	asia-southeast2
Melbourne	australia-southeast2
Bombay	asia-south1
Osaka	asia-northeast2
Seúl	asia-northeast3
Singapur	asia-southeast1
Sídney	australia-southeast1
Taiwán	asia-east1
Tokio	asia-northeast1

En la siguiente tabla, se enumeran las regiones de Europa en las que está disponible BigQuery.

Descripción de la región	Nombre de la región	Detalles
Bélgica	europe-west1	CO2 bajo
Berlín	europe-west10	CO2 bajo
Finlandia	europe-north1	CO2 bajo
Fráncfort	europe-west3	CO2 bajo
Londres	europe-west2	CO2 bajo
Madrid	europe-southwest1	CO2 bajo
Milán	europe-west8
Países Bajos	europe-west4	CO2 bajo
París	europe-west9	CO2 bajo
Turín	europe-west12
Varsovia	europe-central2
Zúrich	europe-west6	CO2 bajo

En la siguiente tabla, se enumeran las regiones de Oriente Medio en las que está disponible BigQuery.

Descripción de la región	Nombre de la región	Detalles
Dammam	me-central2
Doha	me-central1
Tel Aviv	me-west1

En la siguiente tabla, se enumeran las regiones de África en las que está disponible BigQuery.

Descripción de la región	Nombre de la región	Detalles
Johannesburgo	africa-south1

Multirregiones

En la siguiente tabla, se enumeran las multirregiones en las que BigQuery está disponible.

Descripción de la multirregión	Nombre de la multirregión
Centros de datos dentro de los Estados miembros de la Unión Europea^1	EU
Centros de datos en Estados Unidos^2	US

Nota: Seleccionar una ubicación multirregional no proporciona replicación entre regiones ni redundancia regional, por lo que no hay un aumento en la disponibilidad del conjunto de datos en el caso de una interrupción regional. Los datos se almacenan en una sola región dentro de la ubicación geográfica.

¹ Los datos ubicados en la multirregión EU solo se almacenan en una de las siguientes ubicaciones: europe-west1 (Bélgica) o europe-west4 (Países Bajos). BigQuery determina automáticamente la ubicación exacta en la que se almacenan y procesan los datos.

² Los datos ubicados en la multirregión US solo se almacenan en una de las siguientes ubicaciones: us-central1 (Iowa), us-west1 (Oregón) o us-central2 (Oklahoma). BigQuery determina automáticamente la ubicación exacta en la que se almacenan y procesan los datos.

¿Qué sigue?

• Para ver un ejemplo de una consulta programada que usa una cuenta de servicio y que incluye los parámetros @run_date y @run_time, consulta Crea instantáneas de tablas con una consulta programada.