El Servicio de transferencia de datos de BigQuery para Cloud Storage te permite programar cargas de datos recurrentes de Cloud Storage a BigQuery.
Antes de comenzar
Antes de crear una transferencia de Cloud Storage, sigue estos pasos:
- Verifica si completaste todas las acciones requeridas en la página sobre cómo habilitar el Servicio de transferencia de datos de BigQuery.
- Recupera tu URI de Cloud Storage.
- Crea un conjunto de datos de BigQuery para almacenar tus datos.
- Crea la tabla de destino para tu transferencia y especifica la definición de esquema.
Limitaciones
Las transferencias recurrentes de Cloud Storage a BigQuery están sujetas a las siguientes limitaciones:
- Todos los archivos que coincidan con los patrones que define un comodín o los parámetros del entorno de ejecución de tu transferencia deben compartir el mismo esquema que definiste para la tabla de destino, de lo contrario, la transferencia fallará. Los cambios en el esquema de tabla entre ejecuciones también hacen que la transferencia falle.
- Debido a que se pueden crear versiones de los objetos de Cloud Storage, es importante que tengas en cuenta que las transferencias de BigQuery no admiten objetos archivados de Cloud Storage. Los objetos deben estar activos para que se puedan transferir.
- A diferencia de las cargas individuales de datos de Cloud Storage a BigQuery, para las transferencias en curso, debes crear la tabla de destino y el esquema antes de configurar la transferencia. BigQuery no puede crear la tabla como parte del proceso de transferencia de datos recurrentes.
- Las transferencias de Cloud Storage siempre se activan con la preferencia
WRITE_APPEND
, que agrega datos a la tabla de destino. Para obtener más información, consulta la descripción del campowriteDisposition
del objetoJobConfigurationLoad
. - El Servicio de transferencia de datos de BigQuery no garantiza que todos los archivos se transfieran o transfieran solo una vez si se manipulan los archivos de Cloud Storage durante la transferencia.
- Si la ubicación de tu conjunto de datos está configurada en un valor diferente a
US
, el depósito de Cloud Storage regional o multirregional debe estar en la misma región que el conjunto de datos. El Servicio de transferencia de datos de BigQuery no garantiza la coherencia de los datos para las fuentes de datos externas. Los cambios en los datos subyacentes mientras se ejecuta una consulta pueden dar como resultado un comportamiento inesperado.
Según el formato de tus datos de origen de Cloud Storage, puede haber limitaciones adicionales. Para obtener más información, consulta:
Tu depósito de Cloud Storage debe estar en una región o multirregión compatible con la región o multirregión del conjunto de datos de destino en BigQuery. Esto se conoce como colocación. Consulta las ubicaciones de datos de transferencia de Cloud Storage para obtener más información.
Intervalos mínimos
- Se recogen los archivos de origen para su transferencia inmediatamente, sin una edad de archivo mínima.
- El tiempo mínimo de intervalo entre transferencias recurrentes es de 15 minutos. El intervalo predeterminado para una transferencia recurrente es cada 24 horas.
Permisos necesarios
Cuando cargas datos en BigQuery, necesitas permisos para cargar datos en tablas y particiones de BigQuery nuevas o existentes. Si cargas datos de Cloud Storage, también necesitarás acceso al bucket que contiene tus datos. Asegúrate de que tienes los siguientes permisos necesarios:
- BigQuery: Se requieren permisos
bigquery.transfers.update
para crear la transferencia programada. La función de IAM predefinidabigquery.admin
incluye los permisosbigquery.transfers.update
. Para obtener más información sobre las funciones de IAM en el Servicio de transferencia de datos de BigQuery, consulta la referencia del control de acceso. - Cloud Storage: Se requieren permisos
storage.objects.get
en el depósito individual o superior. Si usas un comodín de URI, también debes tener permisosstorage.objects.list
. Si deseas borrar los archivos de origen después de cada transferencia exitosa, también necesitas permisosstorage.objects.delete
. La función de IAM predefinida destorage.objectAdmin
incluye todos estos permisos.
Configura una transferencia de Cloud Storage
Para crear una transferencia de Cloud Storage en el Servicio de transferencia de datos de BigQuery, sigue estos pasos:
Console
Ve a la página de BigQuery en Cloud Console.
Haz clic en Transfers.
Haz clic en Crear.
En la página Crear transferencia, sigue estos pasos:
En la sección Tipo de fuente (Source type), para Fuente (Source), elige Cloud Storage.
En la sección Nombre de la configuración de transferencia (Transfer config name), en Nombre visible (Display name), ingresa el nombre de la transferencia, como
My Transfer
. El nombre de la transferencia puede ser cualquier valor que te permita identificarla con facilidad si es necesario hacerle modificaciones más tarde.En la sección Opciones de programa (Schedule options), en Programa, deja el valor predeterminado, Comenzar ahora (Start now), o haz clic en Comenzar a una hora determinada (Start at a set time).
- En Repeticiones (Repeats), selecciona una opción para la frecuencia con la que se ejecutará la transferencia. El intervalo mínimo es de 15 minutos.
- Diariamente (predeterminada)
- Semanal
- Mensual
- Personalizada. En Programación personalizada, ingresa una frecuencia personalizada. por ejemplo,
every day 00:00
. Consulta Da formato a la programación. - A pedido
En Fecha de inicio y hora de ejecución (Start date and run time), ingresa la fecha y hora para iniciar la transferencia. Si seleccionas Comenzar ahora (Start now), esta opción se inhabilitará.
- En Repeticiones (Repeats), selecciona una opción para la frecuencia con la que se ejecutará la transferencia. El intervalo mínimo es de 15 minutos.
En la sección Configuración de destino (Destination settings), en Conjunto de datos de destino (Destination dataset), selecciona el conjunto de datos que creaste para almacenar tus datos.
En la sección Detalles de fuente de datos (Data source details):
- En Tabla de destino, ingresa el nombre de tu tabla de destino. La tabla de destino debe seguir las reglas de nombres de las tablas. Los nombres de las tablas de destino también admiten parámetros.
- En el URI de Cloud Storage (Cloud Storage URI), ingresa los URI de Cloud Storage. Se admiten comodines y parámetros.
En Preferencia de escritura (Write preference), elige una de las siguientes opciones:
- ADJUNTAR (APPEND) para agregar datos nuevos a tu tabla de destino existente o
- DUPLICAR para actualizar los datos dentro de la tabla de destino y reflejar los datos modificados en la fuente. DUPLICAR reemplaza una copia nueva de los datos en la tabla de destino.
En Borrar archivos de origen después de la transferencia (Delete source files after transfer), marca la casilla si quieres borrar los archivos de origen después de cada transferencia exitosa. Los trabajos de borrado son el mejor esfuerzo. Los trabajos de borrado no se vuelven a intentar si el primer esfuerzo para borrar los archivos de origen falló.
En la sección Opciones de transferencia (Transfer Options), sigue estos pasos:
- En Todos los formatos (All Formats), haz lo siguiente:
- En Cantidad de errores permitidos (Number of errors allowed), ingresa la cantidad máxima de registros erróneos que BigQuery puede ignorar cuando ejecute el trabajo. Si la cantidad de registros erróneos supera este valor, el trabajo falla y se muestra un error de validez en el resultado. El valor predeterminado es
0
. - (Opcional) En Tipos de objetivo decimal, ingresa una lista separada por comas de tipos de datos SQL posibles en los que se puedan convertir los valores decimales de origen. El tipo de datos de SQL que se selecciona para la conversión depende de las siguientes condiciones:
- El tipo de datos seleccionado para la conversión será el primer tipo de datos de la siguiente lista que admite la precisión y la escala de los datos de origen, en este orden: NUMERIC, BIGNUMERIC (Vista previa) y STRING.
- Si ninguno de los tipos de datos enumerados admite la precisión y la escala, se selecciona el tipo de datos que admite el rango más amplio en la lista especificada. Si un valor excede el rango admitido cuando se leen los datos de origen, se mostrará un error.
- El tipo de datos STRING admite todos los valores de precisión y escala.
- Si este campo se deja vacío, el tipo de datos se establecerá de manera predeterminada en “NUMERIC,STRING” para ORC y “NUMERIC” para los otros formatos de archivos.
- Este campo no puede contener tipos de datos duplicados.
- El orden de los tipos de datos que enumeras en este campo se ignora.
- En Cantidad de errores permitidos (Number of errors allowed), ingresa la cantidad máxima de registros erróneos que BigQuery puede ignorar cuando ejecute el trabajo. Si la cantidad de registros erróneos supera este valor, el trabajo falla y se muestra un error de validez en el resultado. El valor predeterminado es
- En JSON, CSV, haz lo siguiente:
- En Ignorar valores desconocidos (Ignore unknown values), marca la casilla si quieres que la transferencia descarte los datos que no coincidan con el esquema de la tabla de destino.
En CSV, haz lo siguiente:
- En Delimitador de campo (Field delimiter), ingresa el carácter que separa los campos. El valor predeterminado es una coma.
- En Filas de encabezado para omitir (Header rows to skip), ingresa la cantidad de filas de encabezado de los archivos de origen si no quieres importarlas. El valor predeterminado es
0
. - En Permitir saltos de línea con comillas (Allow quoted newlines), marca la casilla si quieres permitir saltos de línea en campos entrecomillados.
- En Permitir filas irregulares (Allow jagged rows), marca la casilla de verificación si quieres permitir que se transfieran filas con columnas
NULLABLE
faltantes.
- En Todos los formatos (All Formats), haz lo siguiente:
De forma opcional, en la sección Opciones de notificación (Notifications options), haz lo siguiente:
- Haz clic en el botón de activación para habilitar las notificaciones por correo electrónico. Cuando habilitas esta opción, el administrador de transferencias recibe una notificación por correo electrónico cuando falla una ejecución de transferencia.
- En Seleccionar un tema de Cloud Pub/Sub (Select a Cloud Pub/Sub topic), elige el nombre de tu tema o haz clic en Crear un tema (Create a topic). Con esta opción, se configuran las notificaciones de ejecución de Pub/Sub para tu transferencia.
Haga clic en Save.
bq
Ingresa el comando bq mk
y suministra la marca de creación de transferencias --transfer_config
. También se requieren las siguientes marcas:
--data_source
--display_name
--target_dataset
--params
bq mk \ --transfer_config \ --project_id=project_id \ --data_source=data_source \ --display_name=name \ --target_dataset=dataset \ --params='parameters'
Aquí:
- project_id es el ID del proyecto. Si no proporcionas
--project_id
para especificar un proyecto en particular, se usa el proyecto predeterminado. - data_source es la fuente de datos:
google_cloud_storage
. - name es el nombre visible de la configuración de transferencia. El nombre de la transferencia puede ser cualquier valor que te permita identificarla con facilidad si necesitas modificarla más tarde.
- dataset es el conjunto de datos de destino para la configuración de la transferencia.
- parameters contiene los parámetros para la configuración de la transferencia creada en formato JSON. Por ejemplo:
--params='{"param":"param_value"}'
- Para Cloud Storage, debes proporcionar los parámetros
data_path_template
,destination_table_name_template
yfile_format
.data_path_template
es el URI de Cloud Storage que contiene los archivos que se van a transferir, que puede incluir un comodín.destination_table_name_template
es el nombre de tu tabla de destino Parafile_format
, indica el tipo de archivos que deseas transferir:CSV
,JSON
,AVRO
,PARQUET
oORC
. El valor predeterminado es CSV. - Para todos los valores file_format, puedes incluir el parámetro opcional
max_bad_records
. El valor predeterminado es0
. - Para todos los valores file_format, puedes incluir el parámetro opcional
decimal_target_types
.decimal_target_types
es una lista separada por comas de posibles tipos de datos de SQL en los que se pueden convertir los valores decimales de origen. Si no se proporciona este campo, el tipo de datos se establecerá de forma predeterminada como “NUMERIC,STRING” para ORC y “NUMERIC” para los otros formatos de archivos. - Para los valores JSON o CSV en file_format, puedes incluir el parámetro opcional
ignore_unknown_values
. Este parámetro se ignorará si no has seleccionadoCSV
oJSON
parafile_format
. - Para file_format de CSV, puedes incluir el parámetro opcional
field_delimiter
del carácter que separa los campos. El valor predeterminado es una coma. Este parámetro se ignorará si no has seleccionadoCSV
parafile_format
. - Para el file_format de CSV, puedes incluir el parámetro
skip_leading_rows
opcional a fin de indicar las filas de encabezado que no deseas importar. El valor predeterminado es 0. Este parámetro se ignorará si no has seleccionadoCSV
parafile_format
. - Para file_format de CSV, puedes incluir el parámetro opcional
allow_quoted_newlines
si deseas permitir saltos de línea dentro de los campos entre comillas. Este parámetro se ignorará si no has seleccionadoCSV
parafile_format
. - Para file_format de CVS, puedes incluir el parámetro opcional
allow_jagged_rows
si deseas aceptar filas a las que les faltan columnas opcionales finales. Los valores que faltan se llenarán con valores NULL. Este parámetro se ignorará si no has seleccionadoCSV
parafile_format
. - El parámetro opcional
delete_source_files
borrará los archivos de origen después de cada transferencia exitosa. Los trabajos de borrado no se vuelven a intentar si el primer esfuerzo para borrar los archivos de origen falló. El valor predeterminado dedelete_source_files
es falso.
- Para Cloud Storage, debes proporcionar los parámetros
Por ejemplo, con el siguiente comando se crea una transferencia de Cloud Storage llamada My Transfer
mediante un valor data_path_template
de gs://mybucket/myfile/*.csv
, el conjunto de datos de destino mydataset
y el CSV
como file_format
. En este ejemplo, se incluyen valores no predeterminados para los parámetros opcionales asociados con el file_format CSV
.
La transferencia se crea en el proyecto predeterminado:
bq mk --transfer_config \
--target_dataset=mydataset \
--display_name='My Transfer' \
--params='{"data_path_template":"gs://mybucket/myfile/*.csv",
"destination_table_name_template":"MyTable",
"file_format":"CSV",
"max_bad_records":"1",
"ignore_unknown_values":"true",
"field_delimiter":"|",
"skip_leading_rows":"1",
"allow_quoted_newlines":"true",
"allow_jagged_rows":"false",
"delete_source_files":"true"}' \
--data_source=google_cloud_storage
Después de ejecutar el comando, recibirás un mensaje como el 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 y pega el código de autenticación en la línea de comandos.
API
Usa el método projects.locations.transferConfigs.create
y suministra una instancia del recurso TransferConfig
.
Java
Activa una transferencia de forma manual
Además de las transferencias programadas de forma automática desde Cloud Storage, puedes activar de forma manual una transferencia para cargar archivos de datos adicionales.
Si la configuración de la transferencia está parametrizada, deberás especificar un rango de fechas para el que se iniciarán las transferencias adicionales.
Para activar una transferencia de forma manual, haz lo siguiente:
Console
Ve a la página de BigQuery en Cloud Console.
Haz clic en Transferencias de datos.
Haz clic en tu transferencia.
Haz clic en EJECUTAR TRANSFER NOW o SCHEDULE BACKFILL (para las configuraciones de transferencia parametrizadas del entorno de ejecución).
Si corresponde, selecciona la Fecha de inicio y la Fecha de finalización y, luego, haz clic en Aceptar para confirmar.
En las configuraciones de transferencia parametrizadas del entorno de ejecución, verás las opciones de fecha cuando hagas clic en SCHEDULE BACKFILL.
¿Qué sigue?
- Obtén información sobre el Uso de los parámetros del entorno de ejecución en las transferencias de Cloud Storage
- Obtén más información sobre el Servicio de transferencia de datos de BigQuery