Crea y usa tablas particionadas por tiempo de transferencia

En este documento, se describe cómo crear y usar tablas particionadas por tiempo de transferencia en BigQuery. Para obtener información sobre las tablas particionadas por fecha o marca de tiempo, consulta cómo crear y usar tablas particionadas por fecha o marca de tiempo. Para obtener información sobre las tablas particionadas con rangos de número entero, consulta esta página sobre cómo crear y usar tablas particionadas con rango de número entero.

Luego de crear una tabla particionada por tiempo de transferencia, puedes hacer lo siguiente:

Controlar el acceso a los datos de tu tabla
Obtener información acerca de tus tablas particionadas
Ver una lista de las tablas particionadas en un conjunto de datos
Obtener metadatos de tablas particionadas por medio de metatablas

Para obtener más información sobre cómo administrar tablas particionadas, lo que incluye cómo copiarlas, borrarlas y actualizar sus propiedades, consulta Administra tablas particionadas.

Crea tablas particionadas por tiempo de transferencia

Puedes crear una tabla particionada por tiempo de transferencia en BigQuery de las siguientes maneras:

Mediante el uso de una instrucción DDL CREATE TABLE con un partition_expression
De forma manual mediante Cloud Console o la IU web clásica de BigQuery
Mediante el uso del comando bq mk de la herramienta de línea de comandos
De manera programática, con una llamada al método tables.insert de la API
Mediante las bibliotecas cliente
Desde resultados de consultas
Cuando cargas datos
Mediante la conversión de tablas fragmentadas por fecha en tablas particionadas

Nombres de las tablas

Cuando creas una tabla en BigQuery, el nombre de la tabla debe ser único en cada conjunto de datos. El nombre de la tabla tiene las siguientes características:

Contiene hasta 1,024 caracteres
Contener letras (mayúsculas o minúsculas), números y guiones bajos

Permisos necesarios

Como mínimo, para crear una tabla, debes tener los siguientes permisos:

Permisos bigquery.tables.create para crear la tabla
bigquery.tables.updateData para escribir datos en la tabla mediante un trabajo de carga, de consulta o de copia
bigquery.jobs.create para ejecutar un trabajo de consulta, de carga o de copia que escriba datos en la tabla

Es posible que se necesiten permisos adicionales, como bigquery.tables.getData, para acceder a los datos que escribes en la tabla.

Las siguientes funciones predefinidas de Cloud IAM incluyen los permisos bigquery.tables.create y bigquery.tables.updateData:

bigquery.dataEditor
bigquery.dataOwner
bigquery.admin

Las siguientes funciones predefinidas de Cloud IAM incluyen los permisos bigquery.jobs.create:

bigquery.user
bigquery.jobUser
bigquery.admin

Además, si un usuario tiene permisos bigquery.datasets.create, se le otorga el acceso bigquery.dataOwner cuando crea un conjunto de datos. Con el acceso bigquery.dataOwner, el usuario puede crear y actualizar tablas en el conjunto de datos.

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

Crea una tabla particionada por tiempo de transferencia vacía con una definición de esquema

Cuando creas una tabla particionada por tiempo de transferencia vacía con una definición de esquema, puedes hacer lo siguiente:

Ingresar el esquema mediante Cloud Console o la IU web clásica de BigQuery
Proporcionar el esquema intercalado con la herramienta de línea de comandos
Enviar un archivo de esquema JSON con la herramienta de línea de comandos
Proporcionar el esquema en un recurso de tabla cuando llames al método tables.insert de la API

Si quieres obtener más información acerca de cómo especificar un esquema de tabla, consulta Especifica un esquema.

Una vez que se crea la tabla particionada por tiempo de transferencia, puedes hacer lo siguiente:

Cargarle datos
Escribir resultados de consultas
Copiar datos

Para crear una tabla particionada por tiempo de transferencia vacía con una definición de esquema, sigue estos pasos:

Console

Selecciona un conjunto de datos de la sección Recursos del panel de navegación. Haz clic en Crear tabla en el lado derecho de la ventana.
En la sección Origen (Source) de la página Crear tabla (Create Table), haz clic en Crear tabla vacía (Create empty table).
En la sección Destination (Destino) de la página Create table (Crear tabla), haz lo siguiente:
- En Nombre del conjunto de datos, selecciona el conjunto de datos que corresponda.
- En el campo Nombre de la tabla, ingresa el nombre de la tabla que deseas crear en BigQuery.
- Verifica que Tipo de tabla (Table type) esté establecido en Tabla nativa (Native table).
En la sección Esquema, ingresa la definición del esquema.
- Ingresa la información del esquema de forma manual de la siguiente manera:
  - Habilita Editar como texto y, luego, ingresa el esquema de la tabla como un arreglo JSON.
    Nota: Puedes ver el esquema de una tabla existente en formato JSON si ingresas el siguiente comando en la CLI: bq show --format=prettyjson dataset.table.
  - Usa Agregar campo para ingresar el esquema de forma manual.
En la sección Partition and cluster settings (Configuración de partición y agrupamiento en clústeres), haz lo siguiente:
- En Partitioning (Partición), haz clic en No partitioning (Sin particiones) y selecciona Partition by ingestion time (Particionar por tiempo de transferencia).
Para el Filtro de partición, haz clic en la casilla Exigir filtro de partición a fin de solicitar a los usuarios que incluyan una cláusula WHERE que especifique las particiones que deben consultarse (opcional). Exigir un filtro de partición puede reducir los costos y mejorar el rendimiento. Para obtener más información, lee la sección Consulta tablas particionadas.
De manera opcional, si deseas usar una clave de Cloud Key Management Service, haz clic en Opciones avanzadas y selecciona Clave administrada por el cliente en Encriptación. Si dejas establecida la configuración Clave administrada por Google, BigQuery encripta los datos en reposo.
Haz clic en Crear tabla.

Una vez que se crea la tabla, puedes actualizar el vencimiento, la descripción y las etiquetas de la tabla particionada. No puedes agregar un vencimiento de partición con la IU web de BigQuery luego de crear la tabla.

IU clásica

Haz clic en el ícono de flecha hacia abajo junto al nombre de tu conjunto de datos en el menú de navegación y haz clic en Crear tabla nueva.
En la página Crear tabla, en la sección Datos de origen, haz clic en Crear tabla vacía.
En la página Crear tabla, en la sección Tabla de destino, realiza lo siguiente:
- Para el Nombre de la tabla, elige el conjunto de datos apropiado y, en el campo correspondiente, ingresa el nombre de la tabla que creas en ese momento.
- Verifica que Tipo de tabla (Table type) esté establecido en Tabla nativa (Native table).
En la sección Schema (Esquema), ingresa la definición de esquema de forma manual.
- Para ingresar la información del esquema de forma manual, haz lo siguiente:
  - Haz clic en Edit as text (Editar como texto) y, luego, ingresa el esquema de la tabla como un arreglo JSON:
    
    Nota: Para ver el esquema de una tabla existente en formato JSON, ingresa el siguiente comando en la CLI: bq show --schema --format=prettyjson project_id:dataset.table.
  - Usa Add Field (Agregar campo) para ingresar el esquema:
En la sección Opciones, sigue estos pasos:
- Para Partición, haz clic en Ninguna y selecciona Día.
- En Tipo de encriptación, deja la opción Default. Esta propiedad es para claves de encriptación administradas por el cliente. De forma predeterminada, BigQuery encripta contenido de cliente almacenado en reposo.
Haz clic en Crear tabla.

Una vez que se crea la tabla, puedes actualizar el vencimiento, la descripción y las etiquetas de la tabla particionada. No puedes agregar un vencimiento de partición mediante la IU web de BigQuery luego de crear la tabla.

bq

Usa el comando mk con la marca --table (o la combinación de teclas -t) y la marca -- time_partitioning_type, configurada como DAY o HOUR según corresponda para tu tipo de partición. Puedes proveer la definición del esquema de la tabla de forma intercalada o con un archivo de esquema JSON. Los parámetros opcionales incluyen --expiration, -- description, --time_partitioning_expiration, --destination_kms_key y --label. Si creas una tabla en otro proyecto que no sea el predeterminado, agrega el ID del proyecto al conjunto de datos en el siguiente formato: project_id:dataset.

--destination_kms_key no se muestra aquí. Para obtener más información sobre el uso de esta marca, consulta cómo proteger los datos con claves de Cloud KMS.

Ingresa el siguiente comando para crear una tabla particionada por tiempo de transferencia vacía con una definición de esquema:

bq mk --table \
--expiration integer1 \
--time_partitioning_type=unit_time \
--time_partitioning_expiration integer2 \
--description "description" \
-label key:value,key:value \
project_id:dataset.table \
schema

En el ejemplo anterior, se ilustra lo siguiente:

integer1 es el ciclo de vida predeterminado (en segundos) de la tabla. El valor mínimo es 3,600 segundos (una hora). El tiempo de caducidad se evalúa según la hora UTC actual más el valor del número entero. Si configuras la fecha de vencimiento cuando creas una tabla particionada, se ignora la configuración predeterminada del vencimiento de la tabla para el conjunto de datos. Si configuras este valor, la tabla y todas las particiones se borran después del lapso especificado.
unit_time es DAY o HOUR, según el tipo de partición. El valor predeterminado es DAY cuando no se especifica time_partitioning_type.
integer2 es la duración predeterminada (en segundos) de las particiones de la tabla. No hay valor mínimo. El tiempo de vencimiento se evalúa según la fecha de la partición más el valor de número entero. El vencimiento de la partición es independiente del vencimiento de la tabla, pero no lo anula. Si configuras un vencimiento de partición que suceda después del vencimiento de la tabla, prevalece el vencimiento de la tabla.
description es una descripción de la tabla entre comillas.
key:value es el par clave-valor que representa una etiqueta. Puedes ingresar múltiples etiquetas mediante una lista separada por comas.
project_id es el ID del proyecto.
dataset es un conjunto de datos en tu proyecto.
table es el nombre de la tabla particionada por tiempo que creas.
schema es una definición de esquema intercalado en el formato column:data_type,column:data_type o la ruta al archivo de esquema JSON en tu máquina local.

Cuando especificas el esquema en la línea de comandos, no puedes incluir un tipo RECORD (STRUCT) ni una descripción de la columna, ni tampoco puedes especificar el modo de la columna. Todos los modos están establecidos como NULLABLE de forma predeterminada. Para incluir descripciones, modos y tipos de RECORD, proporciona un archivo de esquema JSON en su lugar.

Ejemplos:

Ingresa el siguiente comando para crear una tabla particionada por tiempo de transferencia llamada mytable en mydataset en tu proyecto predeterminado. El tipo de partición se establece en DAY, el vencimiento de la partición se establece en 259,200 segundos (3 días), el vencimiento de la tabla es de 2,592,000 (1 mes de 30 días), la descripción es This is my time partitioned table y la etiqueta es organization:development. El comando usa la combinación de teclas -t, en lugar de --table. El esquema está especificado de forma intercalada como: qtr:STRING,sales:FLOAT,year:STRING.

bq mk -t \
--expiration 2592000 \
--time_partitioning_type=DAY \
--time_partitioning_expiration 259200 \
--description "This is my time partitioned table" \
--label organization:development \
mydataset.mytable \
qtr:STRING,sales:FLOAT,year:STRING

Ingresa el siguiente comando para crear una tabla particionada por tiempo llamada mytable en myotherproject, no en tu proyecto predeterminado. El tipo de partición se establece en DAY, el vencimiento de la partición se establece en 259,200 segundos (3 días), la descripción es This is my time partitioned table y la etiqueta es organization:development. El comando usa la combinación de teclas -t, en lugar de --table. Este comando no especifica el vencimiento de la tabla. Si el conjunto de datos tiene un vencimiento de tabla predeterminado, se aplica. Si el conjunto de datos no tiene un vencimiento de tabla predeterminado, la tabla no expirará, pero las particiones lo harán luego de 3 días. La ruta al archivo del esquema es /tmp/myschema.json.

bq mk -t \
--time_partitioning_type=DAY \
--time_partitioning_expiration 259200 \
--description "This is my time partitioned table" \
--label organization:development \
myotherproject:mydataset.mytable \
/tmp/myschema.json

Luego de que se crea la tabla, puedes actualizar el vencimiento de la tabla, el vencimiento de las particiones, la descripción y las etiquetas de la tabla particionada por tiempo de transferencia.

API

Llama al método tables.insert con un recurso de tabla definido que especifique las propiedades timePartitioning y schema.

Crea una tabla particionada por tiempo de transferencia a partir del resultado de una consulta

Para crear una tabla particionada a partir del resultado de una consulta, escribe los resultados en una tabla de destino nueva. Puedes crear una tabla particionada nueva si consultas una tabla particionada o una no particionada. No puedes cambiar una tabla existente a una tabla particionada con los resultados de consulta.

Para obtener más información sobre las consultas a tablas particionadas por tiempo, lee Consulta tablas particionadas.

Console

No puedes especificar opciones de partición para una tabla de destino cuando consultas datos con la IU web de consola de BigQuery.

IU clásica

No puedes especificar opciones de partición para una tabla de destino cuando consultas datos mediante la IU web clásica de BigQuery.

bq

Ingresa el comando bq query, especifica la marca --destination_table para crear una tabla permanente basada en los resultados de la consulta y especifica la marca --time_partitioning_type a fin de crear una tabla particionada por tiempo de transferencia de destino. DAY y HOUR son los valores admitidos para --time_partitioning_type, según el nivel de detalle de la partición.

Especifica la marca use_legacy_sql=false para usar la sintaxis de SQL estándar. Para escribir los resultados de las consultas en una tabla que no se encuentra en tu proyecto predeterminado, agrega el ID del proyecto al nombre del conjunto de datos con el siguiente formato: project_id:dataset.

De forma opcional, puedes proporcionar la marca --location y establecer el valor según tu ubicación.

Ingresa el comando siguiente para crear una tabla de destino particionada por tiempo de transferencia nueva a partir de un resultado de consulta:

bq --location=location query \
--destination_table project_id:dataset.table \
--time_partitioning_type=unit_time \
--use_legacy_sql=false \
'query'

Donde:

location es el nombre de tu ubicación. La marca --location es opcional. Por ejemplo, si usas BigQuery en la región de Tokio, puedes establecer el valor de la marca en asia-northeast1. Puedes configurar un valor predeterminado para la ubicación mediante el archivo .bigqueryrc.
project_id es el ID del proyecto.
dataset es el nombre del conjunto de datos que contendrá la nueva tabla particionada por tiempo.
table es el nombre de la tabla particionada por tiempo que creas a partir de los resultados de la consulta.
- unit_time es DAY o HOUR, según el tipo de partición. La configuración predeterminada es DAY cuando no se especifica time_partitioning_type.
query es una consulta en la sintaxis de SQL estándar.

Ejemplos:

Ingresa el siguiente comando para escribir los resultados de la consulta en una tabla de destino particionada por día por tiempo de transferencia llamada mytable en mydataset. El conjunto de datos se encuentra en tu proyecto predeterminado. La consulta obtiene datos de una tabla no particionada: el conjunto de datos públicos Datos de nombres de EE.UU.

bq query \
--destination_table mydataset.mytable \
--time_partitioning_type=DAY \
--use_legacy_sql=false \
'SELECT
   name,
   number
 FROM
   `bigquery-public-data`.usa_names.usa_1910_current
 WHERE
   gender = "M"
 ORDER BY
   number DESC'

Ingresa el siguiente comando para escribir los resultados de la consulta en una tabla de destino particionada por tiempo de transferencia llamada mytable en mydataset, particionada según la fecha de transferencia de datos. El conjunto de datos se encuentra en myotherproject, no en el proyecto predeterminado. La consulta obtiene datos de una tabla no particionada: el conjunto de datos públicos Datos de nombres de EE.UU.

bq query \
--destination_table myotherproject:mydataset.mytable \
--time_partitioning_type=DAY \
--use_legacy_sql=false \
'SELECT
   name,
   number
 FROM
   `bigquery-public-data`.usa_names.usa_1910_current
 WHERE
   gender = "M"
 ORDER BY
   number DESC'

API

A fin de guardar los resultados de la consulta en una tabla particionada por tiempo de transferencia permanente, llama al método jobs.insert, configura un trabajo query y, luego, incluye un valor para las propiedades destinationTable y timePartitioning.

Crea una tabla particionada por tiempo de transferencia cuando cargas datos

Puedes crear una tabla particionada por tiempo de transferencia si especificas las opciones de partición cuando cargas datos en una tabla nueva. No es necesario crear una tabla particionada vacía antes de cargarle datos. Puedes crear una tabla particionada y cargar tus datos al mismo tiempo.

Cuando cargas datos en BigQuery, puedes proporcionar el esquema de tabla o puedes usar la detección automática del esquema si el formato de datos es compatible.

Los decoradores de particiones te permiten cargar datos en una partición específica. A fin de realizar ajustes a las zonas horarias, puedes usar un decorador de particiones para cargar datos en una partición según tu zona horaria de preferencia. Por ejemplo, si te encuentras en la hora estándar del Pacífico (PST), carga todos los datos que se generen el 1 de mayo de 2016 PST en la partición correspondiente a esa fecha con el decorador de particiones adecuado:

table_name$20160501

Para obtener más información, consulta Introducción a la carga de datos en BigQuery.

Convierte tablas fragmentadas por fecha en tablas particionadas por tiempo de transferencia

Si ya creaste tablas fragmentadas por fecha, puedes convertir todo el conjunto de tablas relacionadas en una sola tabla particionada por tiempo de transferencia mediante el comando partition en la herramienta de línea de comandos de bq. Las tablas fragmentadas por fecha deben usar la siguiente nomenclatura: table_YYYYMMDD. Por ejemplo, mytable_20160101, …, mytable_20160331.

Los parámetros opcionales incluyen --time_partitioning_expiration, --location y --time_partitioning_type. Si no se especifica, --time_partitioning_type se establece de forma predeterminada como DAY. Si las tablas de origen o la tabla de destino están en un proyecto distinto de tu proyecto predeterminado, agrega el ID del proyecto al nombre del conjunto de datos en el siguiente formato: project_id:dataset.

Ingresa el siguiente comando para convertir una serie de tablas fragmentadas por fecha en una sola tabla particionada por tiempo de transferencia, particionada por fecha:

bq --location=location partition \
--time_partitioning_type=DAY \
--time_partitioning_expiration integer \
project_id:dataset.source_table_ \
project_id:dataset.destination_table

En el ejemplo anterior, se ilustra lo siguiente:

location es el nombre de tu ubicación. La marca --location es opcional. Por ejemplo, si usas BigQuery en la región de Tokio, debes configurar el valor de la marca como asia-northeast1. Puedes configurar un valor predeterminado para la ubicación mediante el archivo .bigqueryrc.
integer es la duración predeterminada (en segundos) de las particiones de la tabla. No hay valor mínimo. La fecha y hora de vencimiento se evalúa según la suma de la fecha de la partición en formato UTC más el valor del número entero. El vencimiento de la partición es independiente del vencimiento de la tabla, pero no lo anula. Si configuras un vencimiento de partición que suceda después del vencimiento de la tabla, prevalece el vencimiento de la tabla.
project_id es el ID del proyecto.
dataset es un conjunto de datos en tu proyecto.
sourcetable es el prefijo de tu tabla fragmentada por fecha.
destination_table es el nombre de la tabla particionada que creas.

Ejemplos:

Ingresa el siguiente comando para crear una tabla particionada por tiempo de transferencia llamada mytable_partitioned en mydataset en tu proyecto predeterminado. La tabla se particionará por fecha y el vencimiento de la partición se establecerá en 259,200 segundos (3 días). Las tablas fuente fragmentadas por fecha usan el prefijo sourcetable_. Las tablas fuente también se encuentran en tu proyecto predeterminado.

bq partition \
--time_partitioning_type=DAY \
--time_partitioning_expiration 259200 \
mydataset.sourcetable_ \
mydataset.mytable_partitioned

Cuando ejecutas el comando, se crea un trabajo de copia que genera particiones de tablas fragmentadas. Por ejemplo, si las tablas fragmentadas por fecha son sourcetable_20180126 y sourcetable_20180127, el trabajo de copia creará las siguientes particiones: mydataset.mytable_partitioned$20180126 y mydataset.mytable_partitioned$20180127.

Ingresa el siguiente comando para crear una tabla particionada por tiempo de transferencia llamada mytable_partitioned en mydataset. mydataset está en myotherproject, no en tu proyecto predeterminado. La tabla se particionará por fecha y el vencimiento de la partición se establecerá en 86,400 segundos (1 día). Las tablas fuente fragmentadas por fecha usan el prefijo sourcetable_. Las tablas fuente se encuentran en tu proyecto predeterminado.

bq partition \
--time_partitioning_type=DAY \
--time_partitioning_expiration 86400 \
mydataset.sourcetable_ \
myotherproject:mydataset.mytable_partitioned

Ingresa el siguiente comando para crear una tabla particionada por tiempo de transferencia llamada mytable_partitioned en mydataset en tu proyecto predeterminado. mydataset se creó en la región asia-northeast1. La tabla se particionará por fecha y el vencimiento de la partición se establecerá en 259,200 segundos (3 días). Las tablas fuente fragmentadas por fecha usan el prefijo sourcetable_. Las tablas fuente también se encuentran en tu proyecto predeterminado.

bq --location=asia-northeast1 partition \
--time_partitioning_type=DAY \
--time_partitioning_expiration 259200 \
mydataset.sourcetable_ \
mydataset.mytable_partitioned

Controla el acceso a tablas particionadas por tiempo

No puedes asignar controles de acceso directamente a tablas o particiones. Puedes controlar el acceso a las tablas si configuras los controles de acceso al nivel de conjunto de datos o superior.

En lugar de otorgar el acceso a conjuntos de datos individuales, puedes asignar funciones predefinidas de Cloud IAM que otorguen permisos al nivel de proyecto o superior.

También puedes crear funciones personalizadas. Si creas una función personalizada, los permisos que otorgas dependen de las operaciones de tabla que quieres que el usuario, grupo o cuenta de servicio pueda realizar.

Para obtener más información acerca de las funciones y los permisos, consulta los siguientes documentos:

Comprende las funciones en la documentación de Cloud IAM
Funciones y permisos predefinidos de BigQuery
Asigna controles de acceso a conjuntos de datos

Usa tablas particionadas por tiempo de transferencia

Obtén información sobre tablas particionadas por tiempo de transferencia

Tienes las siguientes opciones para obtener información sobre las tablas:

Mediante Cloud Console o la IU web clásica de BigQuery
Mediante el comando bq show de la CLI
Mediante una llamada al método de la API tables.get
Usar bibliotecas cliente

Permisos necesarios

Como mínimo, para obtener información sobre las tablas, debes tener permisos de bigquery.tables.get. Las siguientes funciones predefinidas de Cloud IAM incluyen los permisos bigquery.tables.get:

bigquery.metadataViewer
bigquery.dataViewer
bigquery.dataOwner
bigquery.dataEditor
bigquery.admin

Además, si un usuario tiene permisos bigquery.datasets.create, se le otorga el acceso bigquery.dataOwner cuando crea un conjunto de datos. El acceso bigquery.dataOwner brinda al usuario la capacidad de obtener información sobre las tablas en un conjunto de datos.

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

Obtén información sobre tablas particionadas por tiempo de transferencia

Para obtener información sobre una tabla particionada por tiempo de transferencia, haz lo siguiente:

Console

Abre la IU web de BigQuery en Cloud Console.
Ir a Cloud Console
En el panel de navegación, en la sección Recursos, expande tu proyecto y selecciona un conjunto de datos para enumerar las tablas y vistas que contiene.
Haz clic en el nombre de la tabla.
Haz clic en Detalles. En esta pestaña, se muestra la descripción y la información de la tabla.
Haz clic en la pestaña Schema (Esquema) para ver la definición del esquema de la tabla. Observa la seudocolumna adicional _PARTITIONTIME que contiene la marca de tiempo basada en la fecha para los datos cargados en la tabla.

IU clásica

En el panel de navegación, haz clic en el ícono de flecha hacia abajo que se encuentra a la izquierda de tu conjunto de datos para expandirlo, o haz doble clic en el nombre del conjunto de datos. Con esta acción, se muestran las tablas y vistas del conjunto de datos.
Haz clic en el nombre de la tabla.
Haz clic en Detalles. En la página Detalles de la tabla, se muestra la descripción y la información de la tabla.
Haz clic en la pestaña Schema (Esquema) para ver la definición del esquema de la tabla. Observa la seudocolumna adicional _PARTITIONTIME que contiene la marca de tiempo basada en la fecha para los datos cargados en la tabla.

bq

Emite el comando bq show para mostrar toda la información de la tabla. Usa la marca --schema para mostrar solo la información del esquema de la tabla. La marca --format se puede usar para controlar el resultado.

Si quieres obtener información sobre una tabla en un proyecto que no sea tu proyecto predeterminado, agrega el ID del proyecto al conjunto de datos en el siguiente formato: project_id:dataset.

bq show --schema --format=prettyjson <var>project_id:dataset.table</var>

En el ejemplo anterior, se ilustra lo siguiente:

project_id es el ID del proyecto.
dataset es el nombre del conjunto de datos.
table es el nombre de la tabla.

Ejemplos:

Ingresa el siguiente comando para mostrar toda la información sobre mytable en mydataset. mydataset está en tu proyecto predeterminado.

bq show --format=prettyjson mydataset.mytable

Ingresa el siguiente comando para mostrar toda la información sobre mytable en mydataset. mydataset está en myotherproject, no en tu proyecto predeterminado.

bq show --format=prettyjson myotherproject:mydataset.mytable

Ingresa el comando siguiente para mostrar solo la información del esquema sobre mytable en mydataset. mydataset está en myotherproject, no en tu proyecto predeterminado.

Cuando muestras la información del esquema de una tabla particionada por tiempo, no se muestra la seudocolumna _PARTITIONTIME.

bq show --schema --format=prettyjson myotherproject:mydataset.mytable

API

Llama al método bigquery.tables.get y proporciona los parámetros relevantes.

Enumera las tablas particionadas por tiempo de transferencia en un conjunto de datos

Puedes enumerar las tablas en los conjuntos de datos (incluidas las tablas particionadas) mediante Cloud Console, la IU web clásica de BigQuery, el comando bq ls de la CLI o mediante una llamada al método de API tables.list.

Permisos necesarios

Como mínimo, para enumerar las tablas en un conjunto de datos, debes tener permisos bigquery.tables.list. Las siguientes funciones predefinidas de Cloud IAM incluyen los permisos bigquery.tables.list:

bigquery.user
bigquery.metadataViewer
bigquery.dataViewer
bigquery.dataOwner
bigquery.dataEditor
bigquery.admin

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

Obtén una lista de tablas particionadas

Para ver una lista de las tablas de un conjunto de datos (incluidas las tablas particionadas), haz lo siguiente:

Console

Abre la IU web de BigQuery en Cloud Console.
Ir a Cloud Console
En el panel de navegación, en la sección Recursos, expande tu proyecto y haz clic en tu conjunto de datos.
Desplázate por la lista para ver las tablas en el conjunto de datos. Las tablas, las tablas particionadas, los modelos y las vistas se identifican mediante íconos diferentes.

IU clásica

En la IU web, en el panel de navegación, haz clic en el ícono de flecha hacia abajo que se encuentra a la izquierda de tu conjunto de datos para expandirlo o haz doble clic en su nombre. Esta acción muestra las tablas y vistas del conjunto de datos.
Desplázate por la lista para ver las tablas en el conjunto de datos. Las tablas y las vistas están identificadas con íconos diferentes.

bq

Ejecuta el comando bq ls. Se puede usar la marca --format para controlar el resultado. Si enumeras vistas en un proyecto que no es el predeterminado, agrega el ID del proyecto al conjunto de datos en el formato siguiente: project_id:dataset.

bq ls --format=pretty project_id:dataset

En el ejemplo anterior, se ilustra lo siguiente:

project_id es el ID del proyecto.
dataset es el nombre del conjunto de datos.

Cuando ejecutas el comando, el campo Type muestra TABLE o VIEW. Para las tablas particionadas por tiempo de transferencia, el campo Time Partitioning muestra DAY y el vencimiento de la partición (si se especifica) está en milisegundos.

Por ejemplo:

+-------------------------+-------+----------------------+--------------------------------+
|         tableId         | Type  |        Labels        | Time Partitioning              |
+-------------------------+-------+----------------------+--------------------------------+
| mytable                 | TABLE | department:shipping  |  DAY (expirationMs: 259200000) |
| myview                  | VIEW  |                      |                                |
+-------------------------+-------+----------------------+--------------------------------+

Ejemplos:

Ingresa el comando siguiente para crear una lista de las tablas en el conjunto de datos mydataset en tu proyecto predeterminado.

bq ls --format=pretty mydataset

Ingresa el siguiente comando para enumerar las tablas en el conjunto de datos mydataset en myotherproject.

bq ls --format=pretty myotherproject:mydataset

API

Para mostrar una lista de las tablas con la API, realiza una llamada al método tables.list.

Crea una lista de las particiones de las tablas particionadas por tiempo de transferencia

Puedes crear una lista de las particiones en una tabla particionada por tiempo de transferencia si consultas la seudocolumna _PARTITIONTIME en SQL estándar o la metatabla __PARTITIONS_SUMMARY__ en SQL heredado.

Puedes ejecutar la consulta en Cloud Console, la IU web clásica de BigQuery, con el comando bq query o con una llamada al método jobs.insert y la configuración de un trabajo query.

Permisos necesarios

Para ejecutar un trabajo de consulta que use la metatabla __PARTITIONS_SUMMARY__ o la seudocolumna _PARTITIONTIME, debes tener los permisos bigquery.jobs.create. Las siguientes funciones predefinidas de Cloud IAM incluyen los permisos bigquery.jobs.create:

bigquery.user
bigquery.jobUser
bigquery.admin

También debes tener permisos bigquery.tables.getData. Las siguientes funciones predefinidas de Cloud IAM incluyen los permisos bigquery.tables.getData:

bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
bigquery.dataViewer

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

Enumera las particiones en una tabla particionada por tiempo de transferencia

Puedes enumerar las particiones de una tabla particionada por tiempo de transferencia mediante SQL estándar (opción preferida) o SQL heredado. Para enumerar particiones, haz lo siguiente:

SQL estándar:

Console

Abre la IU web de BigQuery en Cloud Console.
Ir a la IU web de BigQuery
Haz clic en el botón Redactar consulta nueva.
Ingresa el siguiente texto en el cuadro Editor de consultas para consultar la seudocolumna _PARTITIONTIME:
```
SELECT
  _PARTITIONTIME as pt
FROM
  `dataset.table`
GROUP BY 1
```
En el ejemplo anterior, se ilustra lo siguiente:
- dataset es el conjunto de datos que contiene la tabla.
- table es el nombre de la tabla.
(Opcional) Haz clic en Más (More) y selecciona Configuración de consulta (Query settings).
Haz clic en Run (Ejecutar).

IU clásica

Ve a la IU web de BigQuery.

Ir a la IU web de BigQuery
Haz clic en el botón Redactar consulta.
Ingresa el siguiente texto en el cuadro Nueva consulta para consultar la seudocolumna _PARTITIONTIME de una tabla:
```
#standardSQL
SELECT
  _PARTITIONTIME as pt
FROM
  `dataset.table`
GROUP BY 1
```
En el ejemplo anterior, se ilustra lo siguiente:
- dataset es el conjunto de datos que contiene la tabla.
- table es el nombre de la tabla.
Haz clic en Mostrar opciones.
Opcional: En Ubicación de procesamiento, haz clic en Sin especificar y elige la ubicación de tus datos.
Haz clic en Ejecutar consulta.

bq

Ingresa la siguiente consulta mediante el comando bq query:

bq --location=location query --use_legacy_sql=false '
SELECT
  _PARTITIONTIME as pt
FROM
  `dataset.table`
GROUP BY 1'

En el ejemplo anterior, se ilustra lo siguiente:

location es el nombre de tu ubicación. La marca --location es opcional. Por ejemplo, si usas BigQuery en la región de Tokio, puedes configurar el valor de la marca como asia-northeast1. Puedes configurar un valor predeterminado para la ubicación mediante el archivo .bigqueryrc.
dataset es el conjunto de datos que contiene la tabla.
table es el nombre de la tabla.

API

Llama al método jobs.insert y configura un trabajo query que consulte la seudocolumna _PARTITIONTIME de la tabla.

Especifica tu ubicación en la propiedad location en la sección jobReference del recurso de trabajo.

SQL heredado:

Console

Abre la IU web de BigQuery en Cloud Console.
Ir a la IU web de BigQuery
Haz clic en el botón Redactar consulta nueva.
Ingresa el siguiente texto en el cuadro Editor de consulta para consultar la metatabla __PARTITIONS_SUMMARY__:
```
#legacySQL
SELECT
  partition_id
FROM
  [dataset.table$__PARTITIONS_SUMMARY__]
```
En el ejemplo anterior, se ilustra lo siguiente:
- dataset es el conjunto de datos que contiene la tabla.
- table es el nombre de la tabla.
Haz clic en Más (More) y selecciona Configuración de consulta (Query settings).
En Ubicación de procesamiento, haz clic en Selección automática y elige la ubicación de tus datos (opcional). Puedes dejar activada la selección automática para la ubicación de procesamiento si tus datos se encuentran en la ubicación multirregión US o EU. Cuando tus datos están en US o EU, la ubicación de procesamiento se detecta de forma automática.
Haz clic en Run (Ejecutar).

IU clásica

Ve a la IU web de BigQuery.

Ir a la IU web de BigQuery
Haz clic en el botón Redactar consulta.
Ingresa el siguiente texto en el cuadro de Nueva consulta para consultar la metatabla __PARTITIONS_SUMMARY__ de una tabla:
```
#legacySQL
SELECT
   partition_id
 FROM
   [dataset.table$__PARTITIONS_SUMMARY__]
```
En el ejemplo anterior, se ilustra lo siguiente:
- dataset es el conjunto de datos que contiene la tabla.
- table es el nombre de la tabla.
Haz clic en Mostrar opciones.
Opcional: En Ubicación de procesamiento, haz clic en Sin especificar y elige la ubicación de tus datos.
Haz clic en Ejecutar consulta.

bq

Ingresa la siguiente consulta mediante el comando bq query:

bq --location=location query --use_legacy_sql=true '
SELECT
   partition_id
 FROM
   [dataset.table$__PARTITIONS_SUMMARY__]'

En el ejemplo anterior, se ilustra lo siguiente:

location es el nombre de tu ubicación. La marca --location es opcional. Por ejemplo, si usas BigQuery en la región de Tokio, puedes configurar el valor de la marca como asia-northeast1. Puedes configurar un valor predeterminado para la ubicación mediante el archivo .bigqueryrc.
dataset es el conjunto de datos que contiene la tabla.
table es el nombre de la tabla.

API

Llama al método jobs.insert y configura un trabajo query que consulte la metatabla __PARTITIONS_SUMMARY__.

Especifica tu ubicación en la propiedad location en la sección jobReference del recurso de trabajo.

Obtén los metadatos de la tabla con metatablas

Puedes obtener información sobre las tablas particionadas con tablas especiales llamadas metatablas. Las metatablas contienen metadatos como la lista de tablas y vistas en un conjunto de datos. Las metatablas son de solo lectura.

Obtén metadatos de partición con metatablas

La metatabla __PARTITIONS_SUMMARY__ es una tabla especial cuyos contenidos representan metadatos de particiones en una tabla particionada por tiempo. La metatabla __PARTITIONS_SUMMARY__ es de solo lectura.

Para acceder a los metadatos sobre particiones en una tabla particionada por tiempo, usa la metatabla __PARTITIONS_SUMMARY__ en la declaración SELECT de una consulta. Tienes las siguientes opciones para ejecutar la consulta:

Usar Cloud Console o la IU web clásica de BigQuery
Mediante el comando bq query de la herramienta de línea de comandos
Con una llamada al método jobs.insert de la API y la configuración de un trabajo query
Usar bibliotecas cliente

Por ahora, SQL estándar no es compatible con el separador de decorador de partición ($), por lo que no puedes consultar __PARTITIONS_SUMMARY__ con SQL estándar. Una consulta de SQL heredado que usa la metatabla __PARTITIONS_SUMMARY__ se ve de la siguiente manera:

SELECT
  column
FROM
  [dataset.table$__PARTITIONS_SUMMARY__]

En el ejemplo anterior, se ilustra lo siguiente:

dataset es el nombre del conjunto de datos.
table es el nombre de la tabla particionada por tiempo.
column es una de las siguientes opciones:

Valor	Descripción
`project_id`	Nombre del proyecto.
`dataset_id`	Nombre del conjunto de datos.
`table_id`	Nombre de la tabla particionada por tiempo.
`partition_id`	Nombre (fecha) de la partición.
`creation_time`	El momento en que se creó la partición, expresado como la cantidad de milisegundos transcurridos desde el 1 de enero de 1970 UTC.
`last_modified_time`	El momento en que se modificó la partición por última vez, expresado como la cantidad de milisegundos transcurridos desde el 1 de enero de 1970 UTC.

Permisos sobre la metatabla de particiones

Como mínimo, para ejecutar un trabajo de consulta que use la metatabla __PARTITIONS_SUMMARY__, debes tener permisos bigquery.jobs.create. Las siguientes funciones predefinidas de Cloud IAM incluyen los permisos bigquery.jobs.create:

bigquery.user
bigquery.jobUser
bigquery.admin

También debes tener permisos bigquery.tables.getData. Las siguientes funciones predefinidas de Cloud IAM incluyen los permisos bigquery.tables.getData:

bigquery.dataViewer
bigquery.dataEditor
bigquery.dataOwner
bigquery.admin

Para obtener más información sobre las funciones de Cloud IAM en BigQuery, consulta la sección sobre Control de acceso.

Ejemplos de metatablas de partición

La siguiente consulta recupera todos los metadatos de partición de una tabla particionada por tiempo llamada mydataset.mytable.

Console

#legacySQL
SELECT
  *
FROM
  [mydataset.mytable$__PARTITIONS_SUMMARY__]

IU clásica

#legacySQL
SELECT
  *
FROM
  [mydataset.mytable$__PARTITIONS_SUMMARY__]

CLI

bq query --use_legacy_sql=true '
SELECT
  *
FROM
  [mydataset.mytable$__PARTITIONS_SUMMARY__]'

El resultado será similar a esto:

+----------------+------------+----------------+--------------+---------------+--------------------+
|   project_id   | dataset_id |    table_id    | partition_id | creation_time | last_modified_time |
+----------------+------------+----------------+--------------+---------------+--------------------+
| myproject      | mydataset  | mytable        | 20160314     | 1517190224120 | 1517190224997      |
| myproject      | mydataset  | mytable        | 20160315     | 1517190224120 | 1517190224997      |
+----------------+------------+----------------+--------------+---------------+--------------------+

La siguiente consulta muestra cuándo se modificaron por última vez las particiones en mydataset.mytable.

Console

#legacySQL
SELECT
  partition_id,
  last_modified_time
FROM
  [mydataset.mytable$__PARTITIONS_SUMMARY__]

IU clásica

#legacySQL
SELECT
  partition_id,
  last_modified_time
FROM
  [mydataset.mytable$__PARTITIONS_SUMMARY__]

CLI

bq query --use_legacy_sql=true '
SELECT
  partition_id,
  last_modified_time
FROM
  [mydataset.mytable$__PARTITIONS_SUMMARY__]'

El resultado será similar a esto:

+--------------+--------------------+
| partition_id | last_modified_time |
+--------------+--------------------+
| 20160102     |      1471632556179 |
| 20160101     |      1471632538142 |
| 20160103     |      1471632570463 |
+--------------+--------------------+

Para mostrar el campo last_modified_time en un formato legible, usa la función FORMAT_UTC_USEC. Por ejemplo:

Console

#legacySQL
SELECT
  partition_id,
  FORMAT_UTC_USEC(last_modified_time*1000) AS last_modified
FROM
  [mydataset.table1$__PARTITIONS_SUMMARY__]

IU clásica

#legacySQL
SELECT
  partition_id,
  FORMAT_UTC_USEC(last_modified_time*1000) AS last_modified
FROM
  [mydataset.table1$__PARTITIONS_SUMMARY__]

CLI

bq query --use_legacy_sql=true '
SELECT
  partition_id,
  FORMAT_UTC_USEC(last_modified_time*1000) AS last_modified
FROM
  [mydataset.mytable$__PARTITIONS_SUMMARY__]'

El resultado será similar a esto:

+--------------+----------------------------+
| partition_id |       last_modified        |
+--------------+----------------------------+
| 20160103     | 2016-08-19 18:49:30.463000 |
| 20160102     | 2016-08-19 18:49:16.179000 |
| 20160101     | 2016-08-19 18:48:58.142000 |
+--------------+----------------------------+

Ejemplo: crea una tabla particionada por tiempo de transferencia a partir de los resultados de consultas

En este ejemplo, creas una tabla particionada por tiempo de transferencia con la herramienta de línea de comandos y agregas datos a las tres particiones con los resultados de las consultas. La tabla contendrá datos del tiempo, particionados por fecha, de los primeros tres días de 2016.

En este ejemplo, se consulta el conjunto de datos del tiempo de NOAA GSOD de las temperaturas de los primeros tres días de 2016 y se escriben los resultados en una tabla particionada.

Paso 1. Crea una tabla de tiempo de transferencia vacía, particionada por fecha, llamada temps en un conjunto de datos llamado mydataset. No es necesario especificar un esquema para la tabla. El esquema de los resultados de consulta se usa como la definición de esquema para la tabla.

bq mk --time_partitioning_type=DAY mydataset.temps

Para ver la configuración, usa el comando bq show:

bq show --format=prettyjson mydataset.temps

Busca la entrada timePartitioning en el resultado del comando bq show:

{
  ...
  "timePartitioning": {
    "type": "DAY"
  },
  "type": "TABLE"
}

Paso 2. Consulta el conjunto de datos del clima de NOAA GSOD para obtener las temperaturas de los primeros tres días de 2016 y escribe los resultados en las particiones correspondientes en la tabla temps. Las siguientes consultas usan la opción --destination_table y la sintaxis de SQL estándar para escribir 100 filas de resultados de consultas en una partición.

Ejecuta la siguiente consulta para escribir las temperaturas del 1 de enero de 2016 en la partición mydataset.temps$20160101:

bq query --use_legacy_sql=false \
--destination_table 'mydataset.temps$20160101' \
'SELECT
   stn,
   temp
 FROM
   `bigquery-public-data`.noaa_gsod.gsod2016
 WHERE
   mo="01"
   AND da="01"
 LIMIT
   100'

Ejecuta la siguiente consulta para escribir las temperaturas del 2 de enero de 2016 en la partición mydataset.temps$20160102:

bq --location=US query --use_legacy_sql=false \
--destination_table 'mydataset.temps$20160102' \
'SELECT
   stn,
   temp
 FROM
   `bigquery-public-data`.noaa_gsod.gsod2016
 WHERE
   mo="01"
   AND da="02"
 LIMIT
   100'

Ejecuta la siguiente consulta para escribir las temperaturas del 3 de enero de 2016 en la partición mydataset.temps$20160103:

bq --location=US query --use_legacy_sql=false \
--destination_table 'mydataset.temps$20160103' \
'SELECT
   stn,
   temp
 FROM
   `bigquery-public-data`.noaa_gsod.gsod2016
 WHERE
   mo="01"
   AND da="03"
 LIMIT
   100'

Paso 3. Confirma que tienes 300 filas en tu tabla mediante el comando bq show.

bq show mydataset.temps

Los resultados muestran el esquema y el total de filas.

  Last modified        Schema       Total Rows   Total Bytes     Expiration      Time Partitioning   Labels   kmsKeyName
 ----------------- ---------------- ------------ ------------- ----------------- ------------------- -------- ------------
  28 Jan 15:03:45   |- stn: string   300          4800          29 Jan 15:00:32   DAY
                    |- temp: float

Próximos pasos

Para obtener una descripción general de la compatibilidad con tablas particionadas en BigQuery, consulta Introducción a las tablas particionadas.
Para aprender a administrar y actualizar tablas particionadas, consulta Administra tablas particionadas.
Si deseas obtener información acerca de cómo consultar tablas particionadas, puedes leer Consulta tablas particionadas.
Para obtener información sobre las tablas particionadas por fecha o marca de tiempo, consulta cómo crear y usar tablas particionadas por fecha o marca de tiempo.
Para obtener información sobre las tablas particionadas con rangos de números enteros, consulta Crea y usa tablas particionadas con rangos de números enteros.