Crea tablas externas de Cloud Storage
BigQuery admite la consulta de datos de Cloud Storage en los siguientes formatos:
- Valores separados por comas (CSV)
- JSON (delimitado por saltos de línea)
- Avro
- ORC
- Parquet
- Exportaciones de Datastore
- Exportaciones de Firestore
BigQuery admite la consulta de datos de Cloud Storage de estas clases de almacenamiento:
- Estándar
- Nearline
- Coldline
- Archive
Para consultar una tabla externa de Cloud Storage, debes tener permisos en la tabla externa y en los archivos de Cloud Storage. En su lugar, recomendamos usar una tabla de BigLake, si es posible. Las tablas de BigLake proporcionan delegación de acceso, por lo que solo necesitas permisos en la tabla de BigLake para consultar los datos de Cloud Storage.
Asegúrate de tener en cuenta la ubicación de tu conjunto de datos y del depósito de Cloud Storage cuando consultas datos almacenados en Cloud Storage.
Antes de empezar
Otorga roles de Identity and Access Management (IAM) que les brindan a los usuarios los permisos necesarios para hacer cada tarea de este documento. Los permisos necesarios para hacer una tarea (si existen) se enumeran en la sección “Permisos necesarios” de la tarea.
Roles obligatorios
Para crear una tabla externa, necesitas el permiso bigquery.tables.create
de BigQuery Identity and Access Management (IAM).
Cada una de los siguientes roles predefinidos de Identity and Access Management incluye este permiso:
- Editor de datos de BigQuery (
roles/bigquery.dataEditor
) - Propietario de datos de BigQuery (
roles/bigquery.dataOwner
) - BigQuery Admin (
roles/bigquery.admin
)
También necesitas los siguientes permisos para acceder al bucket de Cloud Storage que contiene tus datos:
storage.buckets.get
storage.objects.get
storage.objects.list
(obligatorio si usas un comodín de URI)
El rol predefinido de Identity and Access Management, Administrador de almacenamiento de Cloud Storage (roles/storage.admin
) incluye estos permisos.
Si no eres principal en estos roles, pídele a tu administrador que te otorgue acceso o que cree la tabla externa 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.
Permisos de acceso para instancias de Compute Engine
Si, desde una instancia de Compute Engine necesitas consultar una tabla externa vinculada a una fuente de Cloud Storage, la instancia debe tener, al menos, el permiso de acceso de solo lectura de Cloud Storage (https://www.googleapis.com/auth/devstorage.read_only
).
Los permisos controlan el acceso de la instancia de Compute Engine a los productos de Google Cloud, incluido Cloud Storage. Las aplicaciones que se ejecutan en la instancia usan la cuenta de servicio adjuntada a la instancia para llamar a las API de Google Cloud.
Si configuras una instancia de Compute Engine de modo que se ejecute como la cuenta de servicio predeterminada de Compute Engine, de forma predeterminada, se le otorga una cantidad de permisos predeterminados, incluido el permiso https://www.googleapis.com/auth/devstorage.read_only
.
Si, en cambio, configuras la instancia con una cuenta de servicio personalizada, asegúrate de otorgar de forma explícita el permiso https://www.googleapis.com/auth/devstorage.read_only
a la instancia.
Para obtener más información acerca de cómo aplicar permisos a una instancia de Compute Engine, consulta Cambia la cuenta de servicio y los permisos de acceso de una instancia. Para obtener más información sobre las cuentas de servicio de Compute Engine, consulta Cuentas de servicio.
Crea tablas externas en datos sin particiones
Puedes crear una tabla permanente vinculada a tu fuente de datos externa mediante las siguientes opciones:
- Usa la consola de Google Cloud
- Usa el comando
bq mk
. - Mediante la creación de un
ExternalDataConfiguration
cuando uses el método de APItables.insert
- Mediante la ejecución de la declaración de lenguaje de definición de datos (DDL)
CREATE EXTERNAL TABLE
- Usa bibliotecas cliente.
Elegir una de las opciones siguientes:
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, elige Tabla externa.
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
Puedes crear una tabla externa permanente si ejecutas la instrucción de 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` OPTIONS ( format ="TABLE_FORMAT", uris = ['BUCKET_PATH'[,...]] );
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
.TABLE_FORMAT
: el formato de la tabla que deseas crear, por ejemplo,PARQUET
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.
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 usa la detección automática de esquemas para crear una tabla externa llamada sales
que está vinculada a un archivo CSV almacenado en Cloud Storage:
CREATE OR REPLACE EXTERNAL TABLE mydataset.sales OPTIONS ( format = 'CSV', uris = ['gs://mybucket/sales.csv']);
En el siguiente ejemplo, se especifica un esquema de manera explícita y se omite la primera fila en el archivo CSV:
CREATE OR REPLACE EXTERNAL TABLE mydataset.sales ( Region STRING, Quarter STRING, Total_Sales INT64 ) OPTIONS ( format = 'CSV', uris = ['gs://mybucket/sales.csv'], skip_leading_rows = 1);
bq
Para crear una tabla externa, usa el comando bq mk
con la marca --external_table_definition
. Esta marca contiene una ruta de acceso a un archivo de definición de tabla o una definición de tabla intercalada.
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 --source_format=SOURCE_FORMAT \ BUCKET_PATH > DEFINITION_FILE bq mk --table \ --external_table_definition=DEFINITION_FILE \ 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.
DEFINITION_FILE
: es la ruta de acceso al archivo de definición de tabla en tu máquina local.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,...
.
Ejemplo:
bq mkdef --source_format=CSV gs://mybucket/sales.csv > mytable_def
bq mk --table --external_table_definition=mytable_def \
mydataset.mytable \
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 --source_format=CSV --autodetect=true \
gs://mybucket/sales.csv > mytable_def
bq mk --table --external_table_definition=mytable_def \
mydataset.mytable
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
:
bq mk --table \ --external_table_definition=@SOURCE_FORMAT=BUCKET_PATH \ 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.
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.
Ejemplo:
bq mkdef --source_format=CSV gs://mybucket/sales.csv > mytable_def
bq mk --table --external_table_definition=mytable_def \
mydataset.mytable \
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
para habilitar la detección automática de esquemas para las fuentes de datos compatibles.
Java
Antes de probar este ejemplo, sigue las instrucciones de configuración para Java incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. 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.
Node.js
Antes de probar este ejemplo, sigue las instrucciones de configuración para Node.js incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Node.js.
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.
Python
Antes de probar este ejemplo, sigue las instrucciones de configuración para Python incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. 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.
Crea tablas externas en datos con particiones
Puedes crear una tabla externa para los datos con particiones de Hive que residen 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 externa para los datos con particiones de subárbol, elige una de las siguientes opciones:
Console
En la consola de Google Cloud, ve a BigQuery.
- En el panel Explorador, expande tu proyecto y elige 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), elige Google Cloud Storage.
- En Seleccionar archivo del bucket de Cloud Storage, escribe la ruta de acceso a la carpeta de Cloud Storage mediante comodines.
Por ejemplo,
my_bucket/my_files*
. El bucket de Cloud Storage 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, elige el tipo de archivo.
- Elegir la casilla de verificación Partición de datos de origen y, luego, para Seleccionar prefijo de URI de origen, escribe el prefijo de URI de Cloud Storage. Por ejemplo,
gs://my_bucket/my_files
. - En la sección Modo de inferencia de la partición, elige una de las siguientes
opciones:
- Inferir tipos de forma de automática: 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 escribe 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 de forma de automática: configura el modo de detección de esquemas de partición como
- Opcional: Para solicitar un filtro de partición en todas las consultas de esta tabla, elige 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 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 deseas crear.
- En Tipo de tabla, elige Tabla externa.
- En la sección Esquema, escribe la definición del esquema.
- Para habilitar la detección automática de esquemas, elige Detección automática.
- 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 el siguiente ejemplo, se usa la detección automática de claves de partición de Hive:
CREATE EXTERNAL TABLE `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME` WITH PARTITION COLUMNS OPTIONS ( format = 'SOURCE_FORMAT', uris = ['GCS_URIS'], hive_partition_uri_prefix = 'GCS_URI_SHARED_PREFIX', require_hive_partition_filter = BOOLEAN);
Reemplaza lo siguiente:
SOURCE_FORMAT
: Es el formato de la fuente de datos externa, comoPARQUET
.GCS_URIS
: Es la ruta a la carpeta de Cloud Storage, en el formato de comodín.GCS_URI_SHARED_PREFIX
: Es el prefijo del URI de origen sin el comodín.BOOLEAN
: especifica si se requiere un filtro de predicado en el momento de la consulta. Esta marca es opcional. El valor predeterminado esfalse
.
En el ejemplo siguiente, se usan claves y tipos de partición personalizados de Hive mediante la enumeración en la cláusula WITH PARTITION COLUMNS
:
CREATE EXTERNAL TABLE `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME` WITH PARTITION COLUMNS (PARTITION_COLUMN_LIST) OPTIONS ( format = 'SOURCE_FORMAT', uris = ['GCS_URIS'], hive_partition_uri_prefix = 'GCS_URI_SHARED_PREFIX', require_hive_partition_filter = BOOLEAN);
Reemplaza lo siguiente:
PARTITION_COLUMN_LIST
: una lista de columnas que siguen el mismo orden en la ruta de la carpeta de Cloud Storage, en el siguiente formato:
KEY1 TYPE1, KEY2 TYPE2
En el siguiente ejemplo, se crea una tabla particionada de forma externa. Usa la detección automática de esquemas para detectar el esquema de archivos y el diseño de partición de subárbol. Si la ruta externa es gs://bucket/path/field_1=first/field_2=1/data.parquet
, las columnas de partición se detectan como field_1
(STRING
) y field_2
(INT64
).
CREATE EXTERNAL TABLE dataset.AutoHivePartitionedTable WITH PARTITION COLUMNS OPTIONS ( uris = ['gs://bucket/path/*'], format = 'PARQUET', hive_partition_uri_prefix = 'gs://bucket/path', require_hive_partition_filter = false);
En el siguiente ejemplo, se crean una tabla particionada de forma externa mediante la especificación explícita de las columnas de partición. En este ejemplo, se supone que la ruta de acceso al archivo externo tiene el patrón gs://bucket/path/field_1=first/field_2=1/data.parquet
.
CREATE EXTERNAL TABLE dataset.CustomHivePartitionedTable WITH PARTITION COLUMNS ( field_1 STRING, -- column order must match the external path field_2 INT64) OPTIONS ( uris = ['gs://bucket/path/*'], format = 'PARQUET', hive_partition_uri_prefix = 'gs://bucket/path', require_hive_partition_filter = false);
bq
Primero, usa el comando bq mkdef
para crear un archivo de definición de tablas:
bq mkdef \ --source_format=SOURCE_FORMAT \ --hive_partitioning_mode=PARTITIONING_MODE \ --hive_partitioning_source_uri_prefix=GCS_URI_SHARED_PREFIX \ --require_hive_partition_filter=BOOLEAN \ GCS_URIS > DEFINITION_FILE
Reemplaza lo siguiente:
SOURCE_FORMAT
: El formato de la fuente de datos externos. Por ejemplo,CSV
.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
.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 externa:
bq mk --external_table_definition=DEFINITION_FILE \ DATASET_NAME.TABLE_NAME \ SCHEMA
Reemplaza lo siguiente:
DEFINITION_FILE
es la ruta de acceso al archivo de definición de tablas.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 de subárbol AUTO
:
bq mkdef --source_format=CSV \
--hive_partitioning_mode=AUTO \
--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 STRING
:
bq mkdef --source_format=CSV \
--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 \
--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 subárbol mediante la API de BigQuery, incluye un objeto hivePartitioningOptions en el objeto ExternalDataConfiguration cuando crees el archivo de definición de tablas.
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
.
Java
Antes de probar este ejemplo, sigue las instrucciones de configuración para Java incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. 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.
Consulta tablas externas
Para obtener más información, visita Consulta datos de Cloud Storage en tablas externas.
Actualiza las tablas externas a BigLake
Puedes actualizar las tablas basadas en Cloud Storage a tablas de BigLake si asocias la tabla externa a una conexión. Si deseas usar el almacenamiento en caché de metadatos con la tabla de BigLake, puedes especificar la configuración para esto al mismo tiempo. Para obtener detalles de la tabla, como el formato de origen y el URI de origen, consulta Obtén información de la tabla.
Para actualizar una tabla externa a 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.
Ruta de acceso a recursos de Cloud Storage
Cuando creas una tabla externa basada en una fuente de datos de Cloud Storage, debes proporcionar la ruta de acceso a los datos.
La ruta de acceso del recurso de Cloud Storage contiene el nombre del bucket y tu objeto (nombre del archivo). Por ejemplo, si el bucket de Cloud Storage se llama mybucket
y el archivo de datos se llama myfile.csv
, la ruta a la fuente será gs://mybucket/myfile.csv
.
BigQuery no admite rutas de recursos de Cloud Storage que incluyen varias barras consecutivas después de la doble barra inicial.
Los nombres de los objetos de Cloud Storage pueden contener varios caracteres de barras consecutivas (“/”). Sin embargo, BigQuery convierte varias barras consecutivas en una sola barra. Por ejemplo, la ruta de acceso al recurso siguiente, aunque es válida en Cloud Storage, no funciona en BigQuery: gs://bucket/my//object//name
.
Para recuperar el URI del recurso de Cloud Storage, sigue estos pasos:
Abre Cloud Storage Console.
Explora la ubicación del objeto (archivo) que contiene los datos de origen.
Haz clic en el nombre del objeto.
Se abrirá la página Detalles del objeto.
Copia el valor proporcionado en el campo URI de gsutil, que inicia con
gs://
.
Admisión de comodines para el URI de Cloud Storage
Si los datos se separan en varios archivos, puedes usar un asterisco (*) para elegir varios archivos. El uso del comodín de asterisco debe seguir estas reglas:
- El asterisco puede aparecer dentro del nombre del objeto o al final de este.
- No se admite el uso de varios asteriscos. Por ejemplo, la ruta
gs://mybucket/fed-*/temp/*.csv
no es válida. - No se admite el uso de un asterisco con el nombre del bucket.
Ejemplos:
En el ejemplo siguiente, se muestra cómo elegir todos los archivos en todas las carpetas que inician con el prefijo
gs://mybucket/fed-samples/fed-sample
:gs://mybucket/fed-samples/fed-sample*
En el siguiente ejemplo, se muestra cómo elegir solo los archivos con una extensión
.csv
en la carpeta llamadafed-samples
y cualquier subcarpeta defed-samples
:gs://mybucket/fed-samples/*.csv
En el siguiente ejemplo, se muestra cómo elegir archivos con un patrón de nombres de
fed-sample*.csv
en la carpeta llamadafed-samples
. En este ejemplo, no se eligen archivos en subcarpetas defed-samples
.gs://mybucket/fed-samples/fed-sample*.csv
Cuando usas la herramienta de línea de comandos de bq, es posible que debas descartar el asterisco en algunas plataformas.
No puedes usar un comodín de asterisco cuando creas tablas externas vinculadas a exportaciones de Datastore o Firestore.
Limitaciones
Para obtener información sobre las limitaciones que se aplican a las tablas externas, consulta Limitaciones de las tablas externas.
¿Qué sigue?
- Obtén más información sobre las tablas externas.
- Obtén más información sobre tablas de BigLake.