Crea tablas de BigLake de Cloud Storage
En este documento, se describe cómo crear una tabla de BigLake de Cloud Storage. Una tabla de BigLake te permite usar la delegación de acceso para consultar datos estructurados en Cloud Storage. La delegación de acceso separa el acceso a la tabla de BigLake del acceso al almacén de datos subyacente.
Antes de comenzar
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud.
-
Enable the BigQuery Connection API.
Si deseas leer tablas de BigLake de motores de código abierto, como Apache Spark, debes habilitar la API de lectura de almacenamiento de BigQuery.
-
In the Google Cloud console, activate Cloud Shell.
Asegúrate de tener un conjunto de datos de BigQuery.
Asegúrate de que tu versión del SDK de Google Cloud sea 366.0.0 o posterior:
gcloud version
Si es necesario, actualiza el SDK de Google Cloud.
- Opcional: Para Terraform, se requiere la versión 4.25.0 o
una posterior de
terraform-provider-google
. Las versiones deterraform-provider-google
se enumeran en GitHub. Puedes descargar la última versión de Terraform desde las descargas de HashiCorp Terraform.
- Opcional: Para Terraform, se requiere la versión 4.25.0 o
una posterior de
Crea una conexión de recursos de Cloud según tu fuente de datos externa y otórgale acceso a Cloud Storage. Si no tienes los permisos adecuados para crear una conexión, pídele a tu administrador de BigQuery que cree una conexión y la comparta contigo.
Funciones obligatorias
Para crear una tabla de BigLake, necesitas los siguientes permisos de BigQuery Identity and Access Management (IAM):
bigquery.tables.create
bigquery.connections.delegate
El rol predefinido de administración de identidades y accesos de BigQuery (roles/bigquery.admin
) incluye estos permisos.
Si no eres principal en esta función, pídele a tu administrador que te otorgue acceso o que cree la tabla de BigLake por ti.
Para obtener más información sobre las funciones y los permisos de la administración de identidades y accesos en BigQuery, consulta Funciones y permisos predefinidos.
Consideración de la ubicación
Cuando usas Cloud Storage para almacenar archivos de datos, puedes mejorar el rendimiento mediante buckets de Cloud Storage en una región única o en una región doble en lugar de buckets multirregionales.
Crea tablas de BigLake en datos sin particiones
Si estás familiarizado con la creación de tablas en BigQuery, el proceso de creación de una tabla de BigLake es similar. La tabla puede usar cualquier formato de archivo que admita BigLake. Para obtener más información, consulta Limitaciones.
Antes de crear una tabla de BigLake, debes tener un conjunto de datos y una conexión de recursos de Cloud que pueda acceder a Cloud Storage.
Para crear una tabla de BigLake, elige una de las siguientes opciones:
Console
Ve a la página de BigQuery.
En el panel Explorador, expande tu proyecto y elige un conjunto de datos.
Expande la opción
Acciones y haz clic en Crear table.En la sección Fuente, especifica los siguientes detalles:
En Crear tabla desde, elige Google Cloud Storage.
En Elegir un archivo del bucket de GCS o usa un patrón de URI, elige un bucket y un archivo para usar o escribe la ruta con el formato
gs://bucket_name/[folder_name/]file_name
.No puedes especificar varios URI en la consola de Google Cloud, pero puedes elegir varios archivos si especificas un carácter comodín de asterisco (
*
). Por ejemplo,gs://mybucket/file_name*
Si deseas obtener más información, consulta Compatibilidad de comodines para los URI de Cloud Storage.El bucket de Cloud Storage debe estar en la misma ubicación que el conjunto de datos que contiene la tabla que quieres crear.
En Formato de archivo, elige el formato que coincida con tu archivo.
En la sección Destino, especifica los siguientes detalles:
En Proyecto, elige el proyecto en el que deseas crear la tabla.
En Conjunto de datos, elige el conjunto de datos en el que deseas crear la tabla.
En Tabla, escribe el nombre de la tabla que crearás.
En Tipo de tabla, selecciona Tabla externa.
Selecciona Crear una tabla de BigLake mediante una conexión de Cloud Resource.
En ID de conexión, selecciona la conexión que creaste antes.
En la sección Esquema, puedes habilitar la detección automática de esquemas o especificar un esquema de forma manual si tienes un archivo de origen. Si no tienes un archivo de origen, debes especificar un esquema de forma manual.
Para habilitar la detección automática de esquemas, elige la opción Detección automática.
Para especificar un esquema de forma manual, deja sin marcar la opción Detección automática. Habilita Cambiar como texto e escribe el esquema de la tabla como un array JSON.
Para omitir las filas con valores de columna adicionales que no coinciden con el esquema, expande la sección Opciones avanzadas y elige Valores desconocidos.
Haga clic en Crear tabla.
Después de crear la tabla permanente, puedes ejecutar una consulta en ella como si fuera una tabla de BigQuery nativa. Cuando se completa tu consulta, puedes exportar los resultados como archivos CSV o JSON, guardarlos como una tabla o en Hojas de cálculo de Google.
SQL
Usa la declaración DDL CREATE EXTERNAL TABLE
.
Puedes especificar el esquema de forma explícita o usar la detección automática de esquemas para inferir el esquema a partir de los datos externos.
En la consola de Google Cloud, ve a la página de BigQuery.
En el editor de consultas, escribe la siguiente oración:
CREATE EXTERNAL TABLE `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME` WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID` OPTIONS ( format ="TABLE_FORMAT", uris = ['BUCKET_PATH'[,...]], max_staleness = STALENESS_INTERVAL, metadata_cache_mode = 'CACHE_MODE' );
Reemplaza lo siguiente:
PROJECT_ID
: el nombre del proyecto en el que deseas crear la tabla, por ejemplo,myproject
.DATASET
: el nombre del conjunto de datos de BigQuery en el que deseas crear una tabla, por ejemplo,mydataset
EXTERNAL_TABLE_NAME
: el nombre de la tabla que deseas crear, por ejemplo,mytable
.REGION
: la región que contiene la conexión, por ejemplo,us
CONNECTION_ID
: el ID de conexión, por ejemplo,myconnection
Cuando ves los detalles de conexión en la consola de Google Cloud, el ID de conexión es el valor en la última sección del ID de conexión completamente calificado que se muestra en ID de conexión, por ejemplo
projects/myproject/locations/connection_location/connections/myconnection
.TABLE_FORMAT
: el formato de la tabla que deseas crear, por ejemplo,PARQUET
Para obtener más información sobre los formatos compatibles, consulta Limitaciones.
BUCKET_PATH
: la ruta al bucket de Cloud Storage que contiene los datos de la tabla externa, en el formato['gs://bucket_name/[folder_name/]file_name']
.Puedes elegir varios archivos del bucket si especificas un carácter comodín de asterisco (
*
) en la ruta de acceso. Por ejemplo,['gs://mybucket/file_name*']
Si deseas obtener más información, consulta Compatibilidad de comodines para los URI de Cloud Storage.Puedes especificar varios buckets para la opción
uris
si proporcionas varias rutas de acceso.En los siguientes ejemplos, se muestran valores
uris
válidos:['gs://bucket/path1/myfile.csv']
['gs://bucket/path1/*.csv']
['gs://bucket/path1/*', 'gs://bucket/path2/file00*']
Cuando especificas valores
uris
que se orientan a varios archivos, todos esos archivos deben compartir un esquema compatible.Para obtener más información sobre cómo usar los URI de Cloud Storage en BigQuery, consulta Ruta de acceso al recurso de Cloud Storage.
STALENESS_INTERVAL
: especifica si las operaciones que se usan en la tabla de BigLake usan los metadatos almacenados en caché, y qué tan actuales deben ser los metadatos para que la operación los use. Si deseas obtener más información sobre las consideraciones de almacenamiento en caché de metadatos, consulta Almacenamiento de metadatos en caché para mejorar el rendimiento.Para inhabilitar el almacenamiento en caché de metadatos, especifica 0. Esta es la opción predeterminada.
Para habilitar el almacenamiento en caché de metadatos, especifica un valor de literal de intervalo entre 30 minutos y 7 días. Por ejemplo, especifica
INTERVAL 4 HOUR
para un intervalo de inactividad de 4 horas. Con este valor, las operaciones en la tabla usan metadatos almacenados en caché si se actualizaron en las últimas 4 horas. Si los metadatos almacenados en caché son más antiguos, la operación recupera metadatos de Cloud Storage.CACHE_MODE
: especifica si la caché de metadatos se actualiza de forma automática o manual. Si quieres obtener más información sobre las consideraciones de almacenamiento en caché de metadatos, consulta Almacenamiento de metadatos en caché para mejorar el rendimiento.Configúralo como
AUTOMATIC
para que la caché de metadatos se actualice a un intervalo definido por el sistema, por lo general, entre 30 y 60 minutos.Configúralo como
MANUAL
si deseas actualizar la caché de metadatos en un programa que determines. En este caso, puedes llamar al procedimiento del sistemaBQ.REFRESH_EXTERNAL_METADATA_CACHE
para actualizar la caché.Debes configurar
CACHE_MODE
siSTALENESS_INTERVAL
está configurado en un valor mayor que 0.
Haz clic en
Ejecutar.
Si deseas obtener información sobre cómo ejecutar consultas, visita Ejecuta una consulta interactiva.
bq
Opción 1: Archivo de definición de tablas
Usa el comando bq mkdef
para crear un archivo de definición de tablas y, luego, pasa la ruta de acceso del archivo al comando bq mk
de la siguiente manera:
bq mkdef \ --connection_id=CONNECTION_ID \ --source_format=SOURCE_FORMAT \ BUCKET_PATH > DEFINITION_FILE bq mk --table \ --external_table_definition=DEFINITION_FILE \ --max_staleness=STALENESS_INTERVAL \ PROJECT_ID:DATASET.EXTERNAL_TABLE_NAME \ SCHEMA
Reemplaza lo siguiente:
CONNECTION_ID
: el ID de conexión, por ejemplo,myconnection
Cuando ves los detalles de conexión en la consola de Google Cloud, el ID de conexión es el valor en la última sección del ID de conexión completamente calificado que se muestra en ID de conexión, por ejemplo
projects/myproject/locations/connection_location/connections/myconnection
.SOURCE_FORMAT
: El formato de la fuente de datos externos. Por ejemplo,PARQUET
BUCKET_PATH
: la ruta al bucket de Cloud Storage que contiene los datos de la tabla, en el formatogs://bucket_name/[folder_name/]file_pattern
.Puedes elegir varios archivos del bucket si especificas un carácter comodín de asterisco (
*
) en la ruta de accesofile_pattern
. Por ejemplo,gs://mybucket/file00*.parquet
Si deseas obtener más información, consulta Compatibilidad de comodines para los URI de Cloud Storage.Puedes especificar varios buckets para la opción
uris
si proporcionas varias rutas de acceso.En los siguientes ejemplos, se muestran valores
uris
válidos:gs://bucket/path1/myfile.csv
gs://bucket/path1/*.parquet
gs://bucket/path1/file1*
,gs://bucket1/path1/*
Cuando especificas valores
uris
que se orientan a varios archivos, todos esos archivos deben compartir un esquema compatible.Para obtener más información sobre cómo usar los URI de Cloud Storage en BigQuery, consulta Ruta de acceso al recurso de Cloud Storage.
DEFINITION_FILE
: es la ruta de acceso al archivo de definición de tabla en tu máquina local.STALENESS_INTERVAL
: especifica si las operaciones que se usan en la tabla de BigLake y los metadatos almacenados en caché deben usarse para que la operación los use en caché. Si deseas obtener más información sobre las consideraciones de almacenamiento en caché de metadatos, consulta Almacenamiento de metadatos en caché para mejorar el rendimiento.Para inhabilitar el almacenamiento en caché de metadatos, especifica 0. Esta es la opción predeterminada.
Para habilitar el almacenamiento en caché de metadatos, especifica un valor de intervalo entre 30 minutos y 7 días, mediante el siguiente comando:
Y-M D H:M:S
formato que se describe en elINTERVAL
tipo de datos. Por ejemplo, especifica0-0 0 4:0:0
para un intervalo de inactividad de 4 horas. Con este valor, las operaciones en la tabla usan metadatos almacenados en caché si se actualizaron en las últimas 4 horas. Si los metadatos almacenados en caché son más antiguos, la operación recupera metadatos de Cloud Storage.DATASET
: El nombre del conjunto de datos de BigQuery en el que deseas crear una tabla, por ejemplo,mydataset
EXTERNAL_TABLE_NAME
: El nombre de la tabla que deseas crear, por ejemplo,mytable
.SCHEMA
: es el esquema de la tabla de BigLake
Ejemplo:
bq mkdef --connection_id=myconnection --metadata_cache_mode=CACHE_MODE --source_format=CSV 'gs://mybucket/*.csv' > mytable_def bq mk --table --external_table_definition=mytable_def='gs://mybucket/*.csv' --max_staleness=0-0 0 4:0:0 myproject:mydataset.mybiglaketable Region:STRING,Quarter:STRING,Total_sales:INTEGER
Para usar la detección automática de esquemas, configura la marca --autodetect=true
en el comando mkdef
y omite el esquema:
bq mkdef \ --connection_id=myconnection \ --metadata_cache_mode=CACHE_MODE \ --source_format=CSV --autodetect=true \ gs://mybucket/*.csv > mytable_def bq mk \ --table \ --external_table_definition=mytable_def=gs://mybucket/*.csv \ --max_staleness=0-0 0 4:0:0 \ myproject:mydataset.myexternaltable
Opción 2: Definición de tabla intercalada
En lugar de crear un archivo de definición de tablas, puedes pasar la definición de tabla directamente al comando bq mk
:
Usa el decorador @connection
para especificar la conexión que se usará al final de la marca --external_table_definition
.
bq mk --table \ --external_table_definition=@SOURCE_FORMAT=BUCKET_PATH@projects/PROJECT_ID/locations/REGION/connections/CONNECTION_ID \ DATASET_NAME.TABLE_NAME \ SCHEMA
Reemplaza lo siguiente:
SOURCE_FORMAT
: El formato de la fuente de datos externos.Por ejemplo,
CSV
.BUCKET_PATH
: la ruta al bucket de Cloud Storage que contiene los datos de la tabla, en el formatogs://bucket_name/[folder_name/]file_pattern
.Puedes elegir varios archivos del bucket si especificas un carácter comodín de asterisco (
*
) en la ruta de accesofile_pattern
. Por ejemplo,gs://mybucket/file00*.parquet
Si deseas obtener más información, consulta Compatibilidad de comodines para los URI de Cloud Storage.Puedes especificar varios buckets para la opción
uris
si proporcionas varias rutas de acceso.En los siguientes ejemplos, se muestran valores
uris
válidos:gs://bucket/path1/myfile.csv
gs://bucket/path1/*.parquet
gs://bucket/path1/file1*
,gs://bucket1/path1/*
Cuando especificas valores
uris
que se orientan a varios archivos, todos esos archivos deben compartir un esquema compatible.Para obtener más información sobre cómo usar los URI de Cloud Storage en BigQuery, consulta Ruta de acceso al recurso de Cloud Storage.
PROJECT_ID
: el nombre del proyecto en el que deseas crear la tabla, por ejemplo,myproject
.REGION
: la región que contiene la conexión,us
CONNECTION_ID
: el ID de conexión, por ejemplo,myconnection
Cuando ves los detalles de conexión en la consola de Google Cloud, el ID de conexión es el valor en la última sección del ID de conexión completamente calificado que se muestra en ID de conexión, por ejemplo
projects/myproject/locations/connection_location/connections/myconnection
.DATASET_NAME
: es el nombre del conjunto de datos en el que deseas crear la tabla de BigLakeTABLE_NAME
: es el nombre de la tabla BigLakeSCHEMA
: es el esquema de la tabla de BigLake
Ejemplo:
bq mk --table \ --external_table_definition=@CSV=gs://mybucket/*.parquet@projects/myproject/locations/us/connections/myconnection \ --max_staleness=0-0 0 4:0:0 \ myproject:mydataset.myexternaltable \ Region:STRING,Quarter:STRING,Total_sales:INTEGER
API
Llama al método tables.insert
de la API y crea un ExternalDataConfiguration
en el recurso Table
que pasas.
Especifica la propiedad schema
o establece la propiedad autodetect
en true
a fin de habilitar la detección automática de esquemas para las fuentes de datos compatibles.
Especifica la propiedad connectionId
a fin de identificar la conexión que se usará para conectarse a Cloud Storage.
Terraform
En este ejemplo, se crea una tabla de BigLake sobre datos no particionados.
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.
Para aplicar tu configuración de Terraform en un proyecto de Google Cloud, completa los pasos de las siguientes secciones.
Prepara Cloud Shell
- Inicia Cloud Shell
-
Establece el proyecto de Google Cloud predeterminado en el que deseas aplicar tus configuraciones de Terraform.
Solo necesitas ejecutar este comando una vez por proyecto y puedes ejecutarlo en cualquier directorio.
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
Las variables de entorno se anulan si configuras valores explícitos en el archivo de configuración de Terraform.
Prepara el directorio
Cada archivo de configuración de Terraform debe tener su propio directorio (también llamado módulo raíz).
-
En Cloud Shell, crea un directorio y un archivo nuevo dentro de ese directorio. El nombre del archivo debe tener la extensión
.tf
, por ejemplo,main.tf
. En este instructivo, el archivo se denominamain.tf
.mkdir DIRECTORY && cd DIRECTORY && touch main.tf
-
Si sigues un instructivo, puedes copiar el código de muestra en cada sección o paso.
Copia el código de muestra en el
main.tf
recién creado.De manera opcional, copia el código de GitHub. Esto se recomienda cuando el fragmento de Terraform es parte de una solución de extremo a extremo.
- Revisa y modifica los parámetros de muestra que se aplicarán a tu entorno.
- Guarda los cambios.
-
Inicialice Terraform. Solo debes hacerlo una vez por directorio.
terraform init
De manera opcional, incluye la opción
-upgrade
para usar la última versión del proveedor de Google:terraform init -upgrade
Aplica los cambios
-
Revisa la configuración y verifica que los recursos que creará o actualizará Terraform coincidan con tus expectativas:
terraform plan
Corrige la configuración según sea necesario.
-
Para aplicar la configuración de Terraform, ejecuta el siguiente comando y, luego, escribe
yes
cuando se te solicite:terraform apply
Espera hasta que Terraform muestre el mensaje “¡Aplicación completa!”.
- Abre tu proyecto de Google Cloud para ver los resultados. En la consola de Google Cloud, navega a tus recursos en la IU para asegurarte de que Terraform los haya creado o actualizado.
BigLake admite la detección automática de esquemas. Sin embargo, si no proporcionaste un esquema y no se le otorgó acceso a la cuenta de servicio en los pasos anteriores, estos pasos fallarán con un mensaje de acceso denegado si intentas detectar el esquema de forma automática.
Crea tablas de BigLake en datos particionados en Hive
Puedes crear una tabla de BigLake para datos particionados de Hive en Cloud Storage. Después de crear una tabla particionada de forma externa, no podrás cambiar la clave de partición. Debes volver a crear la tabla para cambiar la clave de partición.
Para crear una tabla de BigLake basada en datos particionados de Hive en Cloud Storage, selecciona una de las siguientes opciones:
Consola
Ve a la página de BigQuery.
En el panel Explorador, expande tu proyecto y selecciona un conjunto de datos.
Haz clic en
Ver acciones y, luego, en Crear tabla. Se abrirá el panel Crear tabla.En la sección Fuente, especifica los siguientes detalles:
En Create table from (Crear tabla desde), selecciona Google Cloud Storage.
Proporciona la ruta de acceso a la carpeta mediante comodines. Por ejemplo,
my_bucket/my_files*
. La carpeta debe estar en la misma ubicación que el conjunto de datos que contiene la tabla que deseas crear, agregar o reemplazar.En la lista Formato de archivo, selecciona el tipo de archivo.
Selecciona la casilla de verificación Partición de datos de origen y, luego, especifica los siguientes detalles:
- En Seleccionar prefijo de URI de origen, ingresa el prefijo de URI. Por ejemplo,
gs://my_bucket/my_files
- Opcional: A fin de solicitar un filtro de partición en todas las consultas de esta tabla, selecciona la casilla de verificación Exigir filtro de partición. Exigir un filtro de partición puede reducir los costos y mejorar el rendimiento. Para obtener más información, consulta Filtros de predicado obligatorios en claves de partición de consultas.
En la sección Modo de inferencia de la partición, selecciona una de las siguientes opciones:
- Inferir tipos automáticamente: configura el modo de detección de esquemas de partición como
AUTO
. - Todas las columnas son strings: configura el modo de detección de esquemas de partición como
STRINGS
. - Proporcionar uno propio: configura el modo de detección de esquemas de partición como
CUSTOM
e ingresa de forma manual la información del esquema para las claves de partición. Para obtener más información, consulta Proporciona un esquema de clave de partición personalizado.
- Inferir tipos automáticamente: configura el modo de detección de esquemas de partición como
- En Seleccionar prefijo de URI de origen, ingresa el prefijo de URI. Por ejemplo,
En la sección Destino, especifica los siguientes detalles:
- En Proyecto, selecciona el proyecto en el que deseas crear la tabla.
- En Conjunto de datos, selecciona el conjunto de datos en el que deseas crear la tabla.
- En Tabla, ingresa el nombre de la tabla que deseas crear
- En Tipo de tabla, selecciona Tabla externa.
- Selecciona la casilla de verificación Crear una tabla de BigLake con una conexión de Cloud Resource.
- En ID de conexión, selecciona la conexión que creaste antes.
En la sección Esquema, puedes habilitar la detección automática de esquemas o especificar un esquema de forma manual si tienes un archivo de origen. Si no tienes un archivo de origen, debes especificar un esquema de forma manual.
Para habilitar la detección automática de esquemas, elige la opción Detección automática.
Para especificar un esquema de forma manual, deja sin marcar la opción Detección automática. Habilita Cambiar como texto e escribe el esquema de la tabla como un array JSON.
Para omitir las filas con valores de columna adicionales que no coinciden con el esquema, expande la sección Opciones avanzadas y elige Valores desconocidos.
Haga clic en Crear tabla.
SQL
Usa la declaración DDL CREATE EXTERNAL TABLE
:
En la consola de Google Cloud, ve a la página de BigQuery.
En el editor de consultas, escribe la siguiente oración:
CREATE EXTERNAL TABLE `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME` WITH PARTITION COLUMNS ( PARTITION_COLUMN PARTITION_COLUMN_TYPE, ) WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID` OPTIONS ( hive_partition_uri_prefix = "HIVE_PARTITION_URI_PREFIX", uris=['FILE_PATH'], max_staleness = STALENESS_INTERVAL, metadata_cache_mode = 'CACHE_MODE', format ="TABLE_FORMAT" );
Reemplaza lo siguiente:
PROJECT_ID
: el nombre del proyecto en el que deseas crear la tabla, por ejemplo,myproject
DATASET
: el nombre del conjunto de datos de BigQuery en el que deseas crear una tabla, por ejemplo,mydataset
EXTERNAL_TABLE_NAME
: el nombre de la tabla que deseas crear, por ejemplo,mytable
PARTITION_COLUMN
: el nombre de la columna de particiónPARTITION_COLUMN_TYPE
: el tipo de columna de particiónREGION
: la región que contiene la conexión, por ejemplo,us
CONNECTION_ID
: el ID de conexión, por ejemplo,myconnection
Cuando ves los detalles de conexión en la consola de Google Cloud, el ID de conexión es el valor en la última sección del ID de conexión completamente calificado que se muestra en ID de conexión, por ejemplo
projects/myproject/locations/connection_location/connections/myconnection
.HIVE_PARTITION_URI_PREFIX
: prefijo de URI de partición de Hive, por ejemplo,gs://mybucket/
FILE_PATH
: ruta de acceso a la fuente de datos para la tabla externa que deseas crear, por ejemplo,gs://mybucket/*.parquet
STALENESS_INTERVAL
: especifica si las operaciones que se usan en la tabla de BigLake usan los metadatos almacenados en caché, y qué tan actuales deben ser los metadatos para que la operación los use. Si deseas obtener más información sobre las consideraciones de almacenamiento en caché de metadatos, consulta Almacenamiento de metadatos en caché para mejorar el rendimiento.Para inhabilitar el almacenamiento en caché de metadatos, especifica 0. Esta es la opción predeterminada.
Para habilitar el almacenamiento en caché de metadatos, especifica un valor de literal de intervalo entre 30 minutos y 7 días. Por ejemplo, especifica
INTERVAL 4 HOUR
para un intervalo de inactividad de 4 horas. Con este valor, las operaciones en la tabla usan metadatos almacenados en caché si se actualizaron en las últimas 4 horas. Si los metadatos almacenados en caché son más antiguos, la operación recupera metadatos de Cloud Storage.CACHE_MODE
: especifica si la caché de metadatos se actualiza de forma automática o manual. Si deseas obtener más información sobre las consideraciones de almacenamiento en caché de metadatos, consulta Almacenamiento de metadatos en caché para mejorar el rendimiento.Configúralo como
AUTOMATIC
para que la caché de metadatos se actualice a un intervalo definido por el sistema, por lo general, entre 30 y 60 minutos.Configúralo como
MANUAL
si deseas actualizar la caché de metadatos en un programa que determines. En este caso, puedes llamar al procedimiento del sistemaBQ.REFRESH_EXTERNAL_METADATA_CACHE
para actualizar la caché.Debes configurar
CACHE_MODE
siSTALENESS_INTERVAL
está configurado en un valor mayor que 0.TABLE_FORMAT
: el formato de la tabla que deseas crear, por ejemplo,PARQUET
Haz clic en
Ejecutar.
Si deseas obtener información sobre cómo ejecutar consultas, visita Ejecuta una consulta interactiva.
Ejemplos
En el siguiente ejemplo, se crea una tabla de BigLake sobre datos particionados en la que ocurre lo siguiente:
- El esquema se detecta de forma automática.
- El intervalo de inactividad de la caché de metadatos de la tabla es de 1 día.
- La caché de metadatos se actualiza de forma automática.
CREATE EXTERNAL TABLE `my_dataset.my_table` WITH PARTITION COLUMNS ( sku STRING, ) WITH CONNECTION `us.my-connection` OPTIONS( hive_partition_uri_prefix = "gs://mybucket/products", uris = ['gs://mybucket/products/*'], max_staleness = INTERVAL 1 DAY, metadata_cache_mode = 'AUTOMATIC' );
En el siguiente ejemplo, se crea una tabla de BigLake sobre datos particionados en la que ocurre lo siguiente:
- Se especifica el esquema.
- El intervalo de inactividad de la caché de metadatos de la tabla es de 8 horas.
- La caché de metadatos se debe actualizar de forma manual.
CREATE EXTERNAL TABLE `my_dataset.my_table` ( ProductId INTEGER, ProductName STRING, ProductType STRING ) WITH PARTITION COLUMNS ( sku STRING, ) WITH CONNECTION `us.my-connection` OPTIONS( hive_partition_uri_prefix = "gs://mybucket/products", uris = ['gs://mybucket/products/*'], max_staleness = INTERVAL 8 HOUR, metadata_cache_mode = 'MANUAL' );
bq
Primero, usa el comando bq mkdef
para crear un archivo de definición de tablas:
bq mkdef \ --source_format=SOURCE_FORMAT \ --connection_id=REGION.CONNECTION_ID \ --hive_partitioning_mode=PARTITIONING_MODE \ --hive_partitioning_source_uri_prefix=GCS_URI_SHARED_PREFIX \ --require_hive_partition_filter=BOOLEAN \ --metadata_cache_mode=CACHE_MODE \ GCS_URIS > DEFINITION_FILE
Reemplaza lo siguiente:
SOURCE_FORMAT
: El formato de la fuente de datos externos. Por ejemplo,CSV
REGION
: la región que contiene la conexión, por ejemplo,us
.CONNECTION_ID
: el ID de conexión, por ejemplo,myconnection
.Cuando ves los detalles de conexión en la consola de Google Cloud, el ID de conexión es el valor en la última sección del ID de conexión completamente calificado que se muestra en ID de conexión, por ejemplo
projects/myproject/locations/connection_location/connections/myconnection
.PARTITIONING_MODE
: El modo de partición de subárbol. Usa uno de los siguientes valores:AUTO
: Detecta de forma automática los nombres y tipos de claves.STRINGS
: Convierte de forma de automática los nombres de las claves en strings.CUSTOM
: Codifica el esquema de clave en el prefijo de URI de origen.
GCS_URI_SHARED_PREFIX
: Es el prefijo del URI de origen.BOOLEAN
especifica si se requiere un filtro de predicado en el momento de la consulta. Esta marca es opcional. El valor predeterminado esfalse
.CACHE_MODE
: especifica si la caché de metadatos se actualiza de forma automática o manual. Solo debes incluir esta marca si también planeas usar la marca--max_staleness
en el comandobq mk
posterior para habilitar el almacenamiento en caché de metadatos. Si deseas obtener más información sobre las consideraciones de almacenamiento en caché de metadatos, consulta Almacenamiento en caché de metadatos para el rendimiento.Configúralo como
AUTOMATIC
para que la caché de metadatos se actualice a un intervalo definido por el sistema, por lo general, entre 30 y 60 minutos.Configúralo como
MANUAL
si deseas actualizar la caché de metadatos en un programa que determines. En este caso, puedes llamar al procedimiento del sistemaBQ.REFRESH_EXTERNAL_METADATA_CACHE
para actualizar la caché.Debes configurar
CACHE_MODE
siSTALENESS_INTERVAL
está configurado en un valor mayor que 0.GCS_URIS
: Es la ruta a la carpeta de Cloud Storage, en el formato de comodín.DEFINITION_FILE
: Es la ruta de acceso al archivo de definición de tabla en tu máquina local.
Si PARTITIONING_MODE
es CUSTOM
, incluye el esquema de la clave de partición en el prefijo de URI de origen mediante el siguiente formato:
--hive_partitioning_source_uri_prefix=GCS_URI_SHARED_PREFIX/{KEY1:TYPE1}/{KEY2:TYPE2}/...
Después de crear el archivo de definición de tablas, usa el comando bq mk
para crear la tabla de BigLake:
bq mk --external_table_definition=DEFINITION_FILE \ --max_staleness=STALENESS_INTERVAL \ DATASET_NAME.TABLE_NAME \ SCHEMA
Reemplaza lo siguiente:
DEFINITION_FILE
es la ruta de acceso al archivo de definición de tablas.STALENESS_INTERVAL
: especifica si las operaciones que se usan en la tabla de BigLake y los metadatos almacenados en caché deben usarse para que la operación los use en caché. Si incluyes esta marca, también debes haber especificado un valor para la marca--metadata_cache_mode
en el comando anteriorbq mkdef
. Si deseas obtener más información sobre las consideraciones de almacenamiento en caché de metadatos, consulta Almacenamiento en caché de metadatos para el rendimiento.Para inhabilitar el almacenamiento en caché de metadatos, especifica 0. Esta es la opción predeterminada.
Para habilitar el almacenamiento en caché de metadatos, especifica un valor de intervalo entre 30 minutos y 7 días, mediante
Y-M D H:M:S
formato que se describe en el tipo de datosINTERVAL
. Por ejemplo, especifica0-0 0 4:0:0
para un intervalo de inactividad de 4 horas. Con este valor, las operaciones en la tabla usan metadatos almacenados en caché si se actualizaron en las últimas 4 horas. Si los metadatos almacenados en caché son más antiguos, la operación recupera metadatos de Cloud Storage.DATASET_NAME
: es el nombre del conjunto de datos que contiene la tabla.TABLE_NAME
: es el nombre de la tabla que crearás.SCHEMA
: especifica una ruta a un archivo de esquema JSON o especifica el esquema en el formatofield:data_type,field:data_type,...
. Para usar la detección automática de esquemas, omite este argumento.
Ejemplos
En el siguiente ejemplo, se usa el modo de partición AUTO
de Hive y, también, se configura la caché de metadatos para que tenga un intervalo de inactividad de 12 horas y se actualice de forma automática:
bq mkdef --source_format=CSV \
--connection_id=us.my-connection \
--hive_partitioning_mode=AUTO \
--hive_partitioning_source_uri_prefix=gs://myBucket/myTable \
--metadata_cache_mode=AUTOMATIC \
gs://myBucket/myTable/* > mytable_def
bq mk --external_table_definition=mytable_def \
--max_staleness=0-0 0 12:0:0 \
mydataset.mytable \
Region:STRING,Quarter:STRING,Total_sales:INTEGER
En el siguiente ejemplo, se usa el modo de partición de subárbol STRING
:
bq mkdef --source_format=CSV \
--connection_id=us.my-connection \
--hive_partitioning_mode=STRING \
--hive_partitioning_source_uri_prefix=gs://myBucket/myTable \
gs://myBucket/myTable/* > mytable_def
bq mk --external_table_definition=mytable_def \
mydataset.mytable \
Region:STRING,Quarter:STRING,Total_sales:INTEGER
En el siguiente ejemplo, se usa el modo de partición de subárbol CUSTOM
:
bq mkdef --source_format=CSV \
--connection_id=us.my-connection \
--hive_partitioning_mode=CUSTOM \
--hive_partitioning_source_uri_prefix=gs://myBucket/myTable/{dt:DATE}/{val:STRING} \
gs://myBucket/myTable/* > mytable_def
bq mk --external_table_definition=mytable_def \
mydataset.mytable \
Region:STRING,Quarter:STRING,Total_sales:INTEGER
API
Para configurar la partición de Hive mediante la API de BigQuery, incluye el objeto hivePartitioningOptions
en el objeto ExternalDataConfiguration
cuando crees el Archivo de definición de tabla.
Si deseas crear una tabla de BigLake, también debes especificar un valor para el campo connectionId
.
Si configuras el campo hivePartitioningOptions.mode
como CUSTOM
, debes codificar el esquema de clave de partición en el campo hivePartitioningOptions.sourceUriPrefix
de la siguiente manera: gs://BUCKET/PATH_TO_TABLE/{KEY1:TYPE1}/{KEY2:TYPE2}/...
Para implementar el uso de un filtro de predicado en el momento de la consulta, establece el campo hivePartitioningOptions.requirePartitionFilter
en true
.
Terraform
En este ejemplo, se crea una tabla de BigLake sobre datos particionados.
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.
Para aplicar tu configuración de Terraform en un proyecto de Google Cloud, completa los pasos de las siguientes secciones.
Prepara Cloud Shell
- Inicia Cloud Shell
-
Establece el proyecto de Google Cloud predeterminado en el que deseas aplicar tus configuraciones de Terraform.
Solo necesitas ejecutar este comando una vez por proyecto y puedes ejecutarlo en cualquier directorio.
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
Las variables de entorno se anulan si configuras valores explícitos en el archivo de configuración de Terraform.
Prepara el directorio
Cada archivo de configuración de Terraform debe tener su propio directorio (también llamado módulo raíz).
-
En Cloud Shell, crea un directorio y un archivo nuevo dentro de ese directorio. El nombre del archivo debe tener la extensión
.tf
, por ejemplo,main.tf
. En este instructivo, el archivo se denominamain.tf
.mkdir DIRECTORY && cd DIRECTORY && touch main.tf
-
Si sigues un instructivo, puedes copiar el código de muestra en cada sección o paso.
Copia el código de muestra en el
main.tf
recién creado.De manera opcional, copia el código de GitHub. Esto se recomienda cuando el fragmento de Terraform es parte de una solución de extremo a extremo.
- Revisa y modifica los parámetros de muestra que se aplicarán a tu entorno.
- Guarda los cambios.
-
Inicialice Terraform. Solo debes hacerlo una vez por directorio.
terraform init
De manera opcional, incluye la opción
-upgrade
para usar la última versión del proveedor de Google:terraform init -upgrade
Aplica los cambios
-
Revisa la configuración y verifica que los recursos que creará o actualizará Terraform coincidan con tus expectativas:
terraform plan
Corrige la configuración según sea necesario.
-
Para aplicar la configuración de Terraform, ejecuta el siguiente comando y, luego, escribe
yes
cuando se te solicite:terraform apply
Espera hasta que Terraform muestre el mensaje “¡Aplicación completa!”.
- Abre tu proyecto de Google Cloud para ver los resultados. En la consola de Google Cloud, navega a tus recursos en la IU para asegurarte de que Terraform los haya creado o actualizado.
Configura las políticas de control de acceso
Puedes usar varios métodos para controlar el acceso a las tablas de BigLake:
Para obtener instrucciones sobre cómo configurar la seguridad a nivel de columna, consulta la guía de seguridad a nivel de columna.
Para obtener instrucciones sobre cómo configurar el enmascaramiento de datos, consulta la guía de enmascaramiento de datos.
Para obtener instrucciones sobre cómo configurar la seguridad a nivel de fila, consulta la guía de seguridad a nivel de fila.
Por ejemplo, supongamos que deseas limitar el acceso a las filas de la tabla mytable
en el conjunto de datos mydataset
:
+---------+---------+-------+ | country | product | price | +---------+---------+-------+ | US | phone | 100 | | JP | tablet | 300 | | UK | laptop | 200 | +---------+---------+-------+
Puedes crear un filtro a nivel de fila para Kim (kim@example.com
) que restrinja su acceso a las filas en las que country
es igual a US
.
CREATE ROW ACCESS POLICY only_us_filter ON mydataset.mytable GRANT TO ('user:kim@example.com') FILTER USING (country = 'US');
Luego, Kim ejecuta la siguiente consulta:
SELECT * FROM projectid.mydataset.mytable;
En el resultado, solo se muestran las filas en las que country
es igual a US
:
+---------+---------+-------+ | country | product | price | +---------+---------+-------+ | US | phone | 100 | +---------+---------+-------+
Consulta tablas de BigLake
Para obtener más información, ve a Consulta datos de Cloud Storage en tablas de BigLake.
Actualiza las tablas de BigLake
Puedes actualizar las tablas de BigLake si es necesario, por ejemplo, para cambiar su almacenamiento en caché de metadatos. Para obtener detalles de la tabla, como el formato de origen y el URI de origen, consulta Obtén información de la tabla.
También puedes usar este mismo procedimiento para actualizar las tablas externas basadas en Cloud Storage a tablas de BigLake mediante la asociación de la tabla externa a una conexión. Para obtener más información, consulta Actualiza las tablas externas a tablas de BigLake.
Para actualizar una tabla de BigLake, elige una de las siguientes opciones:
SQL
Usa la declaración DDL CREATE OR REPLACE EXTERNAL TABLE
para actualizar una tabla:
En la consola de Google Cloud, ve a la página de BigQuery.
En el editor de consultas, escribe la siguiente oración:
CREATE OR REPLACE EXTERNAL TABLE `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME` WITH CONNECTION `REGION.CONNECTION_ID` OPTIONS( format ="TABLE_FORMAT", uris = ['BUCKET_PATH'], max_staleness = STALENESS_INTERVAL, metadata_cache_mode = 'CACHE_MODE' );
Reemplaza lo siguiente:
PROJECT_ID
: el nombre del proyecto que contiene la tablaDATASET
: el nombre del conjunto de datos que contiene la tablaEXTERNAL_TABLE_NAME
: el nombre de la tablaREGION
: la región que contiene la conexiónCONNECTION_ID
: el nombre de la conexión que se usaráTABLE_FORMAT
: el formato que usa la tablaNo puedes cambiar esto cuando actualizas la tabla.
BUCKET_PATH
: la ruta al bucket de Cloud Storage que contiene los datos de la tabla externa, en el formato['gs://bucket_name/[folder_name/]file_name']
.Puedes elegir varios archivos del bucket si especificas un carácter comodín de asterisco (
*
) en la ruta de acceso. Por ejemplo,['gs://mybucket/file_name*']
Si deseas obtener más información, consulta Compatibilidad de comodines para los URI de Cloud Storage.Puedes especificar varios buckets para la opción
uris
si proporcionas varias rutas de acceso.En los siguientes ejemplos, se muestran valores
uris
válidos:['gs://bucket/path1/myfile.csv']
['gs://bucket/path1/*.csv']
['gs://bucket/path1/*', 'gs://bucket/path2/file00*']
Cuando especificas valores
uris
que se orientan a varios archivos, todos esos archivos deben compartir un esquema compatible.Para obtener más información sobre cómo usar los URI de Cloud Storage en BigQuery, consulta Ruta de acceso al recurso de Cloud Storage.
STALENESS_INTERVAL
: especifica si las operaciones en la tabla usan los metadatos almacenados en caché y qué tan recientes deben ser los metadatos almacenados en caché para que la operación los use.Si deseas obtener más información sobre las consideraciones de almacenamiento en caché de metadatos, consulta Almacenamiento de metadatos en caché para mejorar el rendimiento.
Para inhabilitar el almacenamiento en caché de metadatos, especifica 0. Esta es la opción predeterminada.
Para habilitar el almacenamiento en caché de metadatos, especifica un valor de literal de intervalo entre 30 minutos y 7 días. Por ejemplo, especifica
INTERVAL 4 HOUR
para un intervalo de inactividad de 4 horas. Con este valor, las operaciones en la tabla usan metadatos almacenados en caché si se actualizaron en las últimas 4 horas. Si los metadatos almacenados en caché son más antiguos, la operación recupera metadatos de Cloud Storage.CACHE_MODE
: especifica si la caché de metadatos se actualiza de forma automática o manualSi deseas obtener más información sobre las consideraciones de almacenamiento en caché de metadatos, consulta Almacenamiento de metadatos en caché para mejorar el rendimiento.
Configúralo como
AUTOMATIC
para que la caché de metadatos se actualice a un intervalo definido por el sistema, por lo general, entre 30 y 60 minutos.Configúralo como
MANUAL
si deseas actualizar la caché de metadatos en un programa que determines. En este caso, puedes llamar al procedimiento del sistemaBQ.REFRESH_EXTERNAL_METADATA_CACHE
para actualizar la caché.Debes configurar
CACHE_MODE
siSTALENESS_INTERVAL
está configurado en un valor mayor que 0.
Haz clic en
Ejecutar.
Si deseas obtener información sobre cómo ejecutar consultas, visita Ejecuta una consulta interactiva.
bq
Usa los comandos bq mkdef
y bq update
para actualizar una tabla:
Genera una definición de tabla externa, que describa los aspectos de la tabla que se debe cambiar:
bq mkdef --connection_id=PROJECT_ID.REGION.CONNECTION_ID \ --source_format=TABLE_FORMAT \ --metadata_cache_mode=CACHE_MODE \ "BUCKET_PATH" > /tmp/DEFINITION_FILE
Reemplaza lo siguiente:
PROJECT_ID
: el nombre del proyecto que contiene la conexiónREGION
: la región que contiene la conexiónCONNECTION_ID
: el nombre de la conexión que se usaráTABLE_FORMAT
: el formato que usa la tabla No puedes cambiar esto cuando actualizas la tabla.CACHE_MODE
: especifica si la caché de metadatos se actualiza de forma automática o manual. Si deseas obtener más información sobre las consideraciones de almacenamiento en caché de metadatos, consulta Almacenamiento de metadatos en caché para mejorar el rendimiento.Configúralo como
AUTOMATIC
para que la caché de metadatos se actualice a un intervalo definido por el sistema, por lo general, entre 30 y 60 minutos.Configúralo como
MANUAL
si deseas actualizar la caché de metadatos en un programa que determines. En este caso, puedes llamar al procedimiento del sistemaBQ.REFRESH_EXTERNAL_METADATA_CACHE
para actualizar la caché.Debes configurar
CACHE_MODE
siSTALENESS_INTERVAL
está configurado en un valor mayor que 0.BUCKET_PATH
: la ruta al bucket de Cloud Storage que contiene los datos de la tabla externa, en el formatogs://bucket_name/[folder_name/]file_name
.Puedes limitar los archivos elegidos del bucket si especificas un carácter comodín de asterisco (
*
) en la ruta de acceso. Por ejemplo,gs://mybucket/file_name*
Si deseas obtener más información, consulta Compatibilidad de comodines para los URI de Cloud Storage.Puedes especificar varios buckets para la opción
uris
si proporcionas varias rutas de acceso.En los siguientes ejemplos, se muestran valores
uris
válidos:gs://bucket/path1/myfile.csv
gs://bucket/path1/*.csv
gs://bucket/path1/*,gs://bucket/path2/file00*
Cuando especificas valores
uris
que se orientan a varios archivos, todos esos archivos deben compartir un esquema compatible.Para obtener más información sobre cómo usar los URI de Cloud Storage en BigQuery, consulta Ruta de acceso al recurso de Cloud Storage.
DEFINITION_FILE
: el nombre del archivo de definición de tablas que crearás.
Actualiza la tabla con la definición de tabla externa nueva:
bq update --max_staleness=STALENESS_INTERVAL \ --external_table_definition=/tmp/DEFINITION_FILE \ PROJECT_ID:DATASET.EXTERNAL_TABLE_NAME
Reemplaza lo siguiente:
STALENESS_INTERVAL
: especifica si las operaciones en la tabla usan los metadatos almacenados en caché y qué tan recientes deben ser los metadatos almacenados en caché para que la operación los use. Si deseas obtener más información sobre las consideraciones de almacenamiento en caché de metadatos, consulta Almacenamiento de metadatos en caché para mejorar el rendimiento.Para inhabilitar el almacenamiento en caché de metadatos, especifica 0. Esta es la opción predeterminada.
Para habilitar el almacenamiento en caché de metadatos, especifica un valor de intervalo entre 30 minutos y 7 días, mediante el siguiente comando:
Y-M D H:M:S
formato que se describe en elINTERVAL
tipo de datos. Por ejemplo, especifica0-0 0 4:0:0
para un intervalo de inactividad de 4 horas. Con este valor, las operaciones en la tabla usan metadatos almacenados en caché si se actualizaron en las últimas 4 horas. Si los metadatos almacenados en caché son más antiguos, la operación recupera metadatos de Cloud Storage.DEFINITION_FILE
: el nombre del archivo de definición de tablas que creaste o actualizaste.PROJECT_ID
: el nombre del proyecto que contiene la tablaDATASET
: el nombre del conjunto de datos que contiene la tablaEXTERNAL_TABLE_NAME
: El nombre de la tabla.
Ejemplo
En el siguiente ejemplo, se actualiza mytable
para usar metadatos almacenados en caché, siempre que se hayan actualizado en las últimas 4.5 horas, y también actualizar metadatos en caché de forma automática:
bq update --project_id=myproject --max_staleness='0-0 0 4:30:0' \
--external_table_definition=enable_metadata.json mydataset.mytable
En el ejemplo anterior, enable_metadata.json
tiene el siguiente contenido:
{
"metadataCacheMode": "AUTOMATIC"
}
Registros de auditoría
Para obtener más información sobre el registro en BigQuery, consulta Introducción a la supervisión de BigQuery. Para obtener más información sobre el registro en Google Cloud, consulta Cloud Logging.
¿Qué sigue?
- Obtén más información sobre BigLake.
- Más información sobre Cloud Storage
- Obtén información para consultar datos de AWS.
- Obtén información para consultar datos de Azure.