Crea y usa tablas particionadas por fecha o marca de tiempo

En este documento se describe cómo crear y usar tablas particionadas por una columna de DATE o TIMESTAMP. Si deseas obtener más información sobre las tablas particionadas por tiempo de transferencia, consulta esta página sobre cómo crear y usar tablas particionadas por tiempo de transferencia. 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.

Esto es lo que puedes hacer después de crear una tabla particionada:

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, incluidos cómo copiarlas, borrarlas y actualizar sus propiedades, consulta esta página sobre cómo administrar tablas particionadas.

Limitaciones

Las tablas particionadas están sujetas a las siguientes limitaciones:

La columna de partición debe consistir en una columna escalar de DATE o TIMESTAMP. El modo de la columna puede ser REQUIRED o NULLABLE, pero no REPEATED (basada en arreglo).
La columna de partición debe ser un campo de nivel superior. No puedes usar un campo de hoja de un RECORD (STRUCT) como columna de partición.
No puedes usar SQL heredado para realizar consultas en las tablas particionadas o escribir resultados de consultas en tablas particionadas.

Crea tablas particionadas

Puedes crear una tabla particionada en BigQuery de la siguiente manera:

Con Cloud Console o la IU web clásica
Mediante una instrucción CREATE TABLE DDL con una cláusula PARTITION BY que contenga una partition expression
Con el 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
A partir de resultados de consulta
Cuando cargas datos

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:

Hasta 1,024 caracteres
Letras (mayúsculas o minúsculas), números o 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 escribe 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, cuando crea un conjunto de datos, se le otorga el acceso bigquery.dataOwner. El acceso bigquery.dataOwner permite que el usuario cree y actualice 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 vacía con una definición de esquema

No puedes crear una tabla particionada vacía que no tenga una definición de esquema. Se requiere el esquema a fin de identificar la columna usada para crear las particiones.

Esto es lo que puedes hacer cuando creas una tabla particionada vacía con una definición de esquema:

Proporcionar el esquema intercalado con la CLI
Especificar un archivo de esquema JSON con la CLI
Proporciona 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.

Esto es lo que puedes hacer una vez que creas la tabla particionada:

Cargarle datos
Escribir resultados de consultas
Copiar datos

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

Console

En el panel de navegación, en la sección Recursos, expande tu proyecto y selecciona el conjunto de datos.
En el lado derecho de la ventana, en el panel de detalles, haz clic en Crear tabla.
En el panel Crear tabla, en la sección Fuente, sigue estos pasos:
- En Crear tabla a partir de, selecciona Tabla vacía.
En la sección Destino, sigue estos pasos:
- Para el Nombre del conjunto de datos, selecciona el conjunto de datos apropiado y en el campo Nombre de la tabla, escribe el nombre de la tabla que creaste.
- Verifica que Tipo de tabla esté configurado como Tabla nativa.
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.
Para la Configuración de partición y clústeres, haz clic en Sin particionar, selecciona Particionar por campo y elige la columna DATE o TIMESTAMP. Esta opción no está disponible si el esquema no contiene una columna DATE o TIMESTAMP.
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 Cómo consultar tablas particionadas.
Haz clic en Opciones avanzadas y para Encriptación, haz clic en Clave administrada por el cliente a fin de usar una Clave de servicio de administración de claves (opcional). Si dejas establecida la configuración Clave administrada por Google, BigQuery encripta los datos en reposo.
Haz clic en Crear tabla.

DDL

Las declaraciones del lenguaje de definición de datos (DDL) te permiten crear y modificar tablas y vistas con la sintaxis de consulta de SQL estándar.

Obtén más información en Cómo usar instrucciones del lenguaje de definición de datos.

Sigue estos pasos para crear una tabla particionada con una declaración DDL en Cloud Console:

Abre la IU web de BigQuery en Cloud Console.
Ir a Cloud Console
Haz clic en Redactar consulta nueva.
Escribe tu declaración CREATE TABLE del DDL en el área de texto del Editor de consultas.

En la siguiente consulta, se crea una tabla llamada newtable particionada por la columna transaction_date DATE y cuya partición vence en tres días.
```
 CREATE TABLE
   mydataset.newtable (transaction_id INT64,
     transaction_date DATE)
 PARTITION BY
   transaction_date
 OPTIONS
   ( partition_expiration_days=3,
     description="a table partitioned by transaction_date" )
```
Haz clic en Ejecutar. Cuando se completa la consulta, aparece la tabla en el panel Recursos.

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, haz esto:
- 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 esté configurado como Tabla nativa.
En la sección Esquema, ingresa la definición de esquema de forma manual.
- Haz esto para ingresar la información del esquema de forma manual:
  - Haz clic en 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 --schema --format=prettyjson project_id:dataset.table.
  - Usa Argegar campo para ingresar el esquema.
Haz esto en la sección Opciones:
- Para Tipo de partición, haz clic en Ninguna y elige Día.
- Para Campo de partición, elige la columna TIMESTAMP o DATE. El valor predeterminado es _PARTITIONTIME, que crea una tabla particionada por tiempo de transferencia.
- Haz clic en el cuadro Solicitar filtro de partición para solicitar a los usuarios que incluyan una cláusula WHERE que especifique las particiones que se consultarán (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 Cómo consultar tablas particionadas.
- En Encriptación de destino, elige Encriptación administrada por el cliente para usar una Clave del servicio de administración de claves a fin de encriptar la tabla (opcional). Si dejas la configuración Default, BigQuery encripta los datos en reposo con una clave administrada por Google.
Haz clic en Crear tabla.

CLI

Usa el comando mk con la marca --table (o el acceso directo -t), la marca --schema y la marca --time_partitioning_field. Puedes proveer la definición del esquema de la tabla de forma intercalada o a través de un archivo de esquema JSON.

Los parámetros opcionales incluyen --expiration, --description, --time_partitioning_expiration, --destination_kms_key, --require_partition_filter y --label. En este momento, DAY es el único valor admitido para --time_partitioning_type, por lo que esta marca no es obligatoria.

Si estás creando una tabla en un 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 Protege datos con claves de Cloud KMS.

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

bq mk --table \
--expiration integer1 \
--schema schema \
--time_partitioning_field column \
--time_partitioning_expiration integer2 \
--[no]require_partition_filter \
--description "description" \
--label key:value, key:value \
project_id:dataset.table

Donde:

integer1 es la duración predeterminada (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 el tiempo de vencimiento de la tabla cuando creas una tabla particionada por el tiempo, se ignora la configuración de vencimiento de la tabla predeterminada del conjunto de datos. Si configuras este valor, la tabla y todas las particiones se borran después del lapso especificado.
schema es una definición del esquema intercalado en el formato field:data_type,field:data_type o la ruta al archivo del esquema JSON en tu máquina local.
[COLUMN] es el nombre de la columna TIMESTAMP o DATE que se usa para crear las particiones.
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 key:value que representa una etiqueta. Puedes ingresar múltiples etiquetas mediante una lista separada por comas.
project_id es el ID del proyecto.
dataset es el conjunto de datos en tu proyecto.
table es el nombre de la tabla particionada que creaste.

Cuando especificas el esquema en la línea de comandos, no puedes incluir un tipo de RECORD (STRUCT) o una descripción de columna. Tampoco puedes especificar el modo de la columna. Todos los modos predeterminados están establecidos en NULLABLE. 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 llamada mypartitionedtable en mydataset en tu proyecto predeterminado. El vencimiento de la partición se establece en 86,400 segundos (1 día), el vencimiento de la tabla se establece en 2,592,000 (1 mes de 30 días), la descripción se establece en This is my partitioned table y la etiqueta se establece en organization:development. El comando usa el acceso directo -t en lugar de --table.

Se usa la marca --require_partition_filter a fin de solicitar a los usuarios que incluyan una cláusula WHERE que especifique las particiones que deben consultarse. Exigir un filtro de partición puede reducir los costos y mejorar el rendimiento. Para obtener más información, lee la sección Cómo consultar tablas particionadas.

El esquema está especificado de forma intercalada como: ts:TIMESTAMP,column1:STRING,column2:INTEGER,coumn4:STRING. El campo TIMESTAMP especificado ts se usa para crear las particiones.

bq mk -t \
--expiration 2592000 \
--schema 'ts:TIMESTAMP,column1:STRING,column2:INTEGER,coumn4:STRING' \
--time_partitioning_field ts \
--time_partitioning_expiration 86400  \
--require_partition_filter \
--description "This is my partitioned table" \
--label org:dev \
mydataset.mypartitionedtable

Ingresa el siguiente comando para crear una tabla particionada llamada mypartitionedtable en myotherproject, no en tu proyecto predeterminado. El vencimiento de la partición se establece en 259,200 segundos (3 días), la descripción se establece en This is my partitioned table y la etiqueta en organization:development. El comando usa el acceso directo -t en lugar de --table. El comando no especifica un vencimiento de tabla. Si el conjunto de datos tiene un vencimiento de tabla predeterminado, se aplica. Si no lo tiene, la tabla no se vencerá nunca, pero las particiones se vencerán en 3 días.

El esquema se especifica en un archivo JSON local: /tmp/myschema.json. La definición del esquema incluye un campo TIMESTAMP llamado ts que se usa para crear las particiones.

bq mk -t \
--expiration 2592000 \
--schema /tmp/myschema.json \
--time_partitioning_field ts \
--time_partitioning_expiration 86400  \
--description "This is my partitioned table" \
--label org:dev \
myotherproject:mydataset.mypartitionedtable

Después de crear la tabla, puedes usar la CLI para actualizar el vencimiento de la tabla particionada, el vencimiento de la partición, la descripción y las etiquetas de la tabla particionada.

API

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

Go

Antes de probar este ejemplo, sigue las instrucciones de configuración de Go incluidas en Guía de inicio rápido: usa bibliotecas cliente. A fin de obtener más información, consulta la documentación de referencia de la API de BigQuery para Go.

Ver en GitHub Comentarios

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
sampleSchema := bigquery.Schema{
	{Name: "name", Type: bigquery.StringFieldType},
	{Name: "post_abbr", Type: bigquery.IntegerFieldType},
	{Name: "date", Type: bigquery.DateFieldType},
}
metadata := &bigquery.TableMetadata{
	TimePartitioning: &bigquery.TimePartitioning{
		Field:      "date",
		Expiration: 90 * 24 * time.Hour,
	},
	Schema: sampleSchema,
}
tableRef := client.Dataset(datasetID).Table(tableID)
if err := tableRef.Create(ctx, metadata); err != nil {
	return err
}

Node.js

Ver en GitHub Comentarios

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
sampleSchema := bigquery.Schema{
	{Name: "name", Type: bigquery.StringFieldType},
	{Name: "post_abbr", Type: bigquery.IntegerFieldType},
	{Name: "date", Type: bigquery.DateFieldType},
}
metadata := &bigquery.TableMetadata{
	TimePartitioning: &bigquery.TimePartitioning{
		Field:      "date",
		Expiration: 90 * 24 * time.Hour,
	},
	Schema: sampleSchema,
}
tableRef := client.Dataset(datasetID).Table(tableID)
if err := tableRef.Create(ctx, metadata); err != nil {
	return err
}

Python

Ver en GitHub Comentarios

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
sampleSchema := bigquery.Schema{
	{Name: "name", Type: bigquery.StringFieldType},
	{Name: "post_abbr", Type: bigquery.IntegerFieldType},
	{Name: "date", Type: bigquery.DateFieldType},
}
metadata := &bigquery.TableMetadata{
	TimePartitioning: &bigquery.TimePartitioning{
		Field:      "date",
		Expiration: 90 * 24 * time.Hour,
	},
	Schema: sampleSchema,
}
tableRef := client.Dataset(datasetID).Table(tableID)
if err := tableRef.Create(ctx, metadata); err != nil {
	return err
}

Crea tablas particionadas a partir de los resultados de la consulta

Para crear una tabla particionada a partir de un resultado de consulta, escribe los resultados en una tabla de destino nueva. Puedes crear una tabla particionada si realizas consultas tanto en una tabla particionada como en una tabla sin particiones. No puedes transformar una tabla estándar existente en una tabla particionada a partir de los resultados de una consulta.

Cuando creas una tabla particionada a partir del resultado de una consulta, debes usar SQL estándar. Por el momento, SQL heredado no es compatible con las consultas en tablas particionadas o la escritura de resultados de consultas en tablas particionadas.

Los decoradores de particiones te permiten escribir los resultados de la consulta en una partición específica. Por ejemplo, para escribir los resultados en la partición del 1 de mayo de 2016, usa el siguiente decorador de partición:

table_name$20160501

Cuando escribas resultados de consultas en una partición específica por medio de un decorador de particiones, los datos que se escriben deben concordar con el esquema de partición de la tabla. Todas las filas escritas en la partición deberían tener valores que coincidan con la fecha de la partición.

Por ejemplo:

En la siguiente consulta, se recuperan datos del 1 de febrero de 2018 y se escriben en la partición $20180201 de la tabla mytable. La tabla tiene dos columnas: una TIMESTAMP llamada TS y una INT64 llamada a.

bq query \
--nouse_legacy_sql  \
--destination_table=mytable$20180201 \
'SELECT
   TIMESTAMP("2018-02-01") AS TS,
   2 AS a'

En la siguiente consulta, se recuperan datos del 31 de enero de 2018 y se intenta escribirlos en la partición $20180201 de mytable. Esta consulta falla porque los datos que intentas escribir no están dentro de la fecha de la partición.

bq query \
--nouse_legacy_sql  \
--destination_table=T$20180201 \
'SELECT
   TIMESTAMP("2018-01-31") as TS,
   2 as a'

Si deseas obtener más información acerca de cómo anexar o rectificar (reemplazar) datos en tablas particionadas, consulta Anexa y reemplaza datos de tablas particionadas. Si deseas obtener más información acerca de cómo consultar tablas particionadas, lee Consulta tablas particionadas.

Crea una tabla particionada a partir de un resultado de consulta

Sigue estos pasos para crear una tabla particionada a partir de un resultado de consulta:

Console

No puedes especificar opciones de partición para una tabla de destino cuando consultas datos con Cloud Console.

IU clásica

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

CLI

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_field a fin de crear una tabla de destino particionada. En este momento, DAY es el único valor admitido para --time_partitioning_type, por lo que esta marca no es obligatoria.

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.

Proporciona la marca --location y establece el valor en tu ubicación (opcional).

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

bq --location=location query \
--destination_table project_id:dataset.table \
--time_partitioning_field column \
--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, establece el valor de la marca en asia-northeast1. Puedes configurar un valor predeterminado para la ubicación con el archivo .bigqueryrc.
project_id es el ID del proyecto.
dataset es el nombre del conjunto de datos que contendrá la tabla particionada nueva.
table es el nombre de la tabla particionada que creas con los resultados de la consulta.
query es una consulta en la sintaxis de SQL estándar. En este momento, no puedes usar SQL heredado para realizar consultas en las tablas particionadas o escribir resultados de consultas en tablas particionadas.

Ejemplos:

Ingresa el siguiente comando para escribir los resultados de la consulta en una tabla de destino particionada llamada mypartitionedtable en mydataset. mydataset está en tu proyecto predeterminado. La consulta recupera datos de una tabla no particionada: el conjunto de datos públicos sobre accidentes de tráfico fatales de NHTSA. Se usa la columna timestamp_of_crash TIMESTAMP de la tabla para crear las particiones.

bq query \
--destination_table mydataset.mypartitionedtable \
--time_partitioning_field timestamp_of_crash \
--use_legacy_sql=false \
'SELECT
   state_number,
   state_name,
   day_of_crash,
   month_of_crash,
   year_of_crash,
   latitude,
   longitude,
   manner_of_collision,
   number_of_fatalities,
   timestamp_of_crash
 FROM
   `bigquery-public-data`.nhtsa_traffic_fatalities.accident_2016
 LIMIT
   100'

Ingresa el siguiente comando para escribir los resultados de la consulta en una tabla de destino particionada llamada mypartitionedtable en mydataset. mydataset está en myotherproject, no en tu proyecto predeterminado. La consulta recupera datos de una tabla no particionada: el conjunto de datos públicos sobre accidentes de tráfico fatales de NHTSA. Se usa la columna timestamp_of_crash TIMESTAMP de la tabla para crear las particiones.

bq query \
--destination_table myotherproject:mydataset.mypartitionedtable \
--time_partitioning_field timestamp_of_crash \
--use_legacy_sql=false \
'SELECT
   state_number,
   state_name,
   day_of_crash,
   month_of_crash,
   year_of_crash,
   latitude,
   longitude,
   manner_of_collision,
   number_of_fatalities,
   timestamp_of_crash
 FROM
   `bigquery-public-data`.nhtsa_traffic_fatalities.accident_2016
 LIMIT
   100'

API

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

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

Cómo crear una tabla particionada en el momento de cargar datos

Puedes crear una tabla particionada si especificas 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. Por ejemplo, para cargar todos los datos generados el 1 de mayo de 2016 en la partición 20160501, usa el decorador de partición siguiente:

table_name$20160501

Cuando cargues datos en una partición específica mediante un decorador de particiones, los datos que se carguen en la partición deben concordar con el esquema de partición de la tabla. Todas las filas escritas en la partición deberían tener valores que coincidan con la fecha de la partición.

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

Cómo controlar el acceso a las tablas particionadas

No puedes asignar controles de acceso a tablas o vistas de forma directa. El nivel más bajo de recursos de BigQuery al que puedes otorgar acceso es el nivel de conjunto de datos. Para configurar el acceso a las tablas y las vistas, debes otorgar una función de Cloud IAM a una entidad a nivel de conjunto de datos o superior.

Cuando se otorga una función a nivel de conjunto de datos, se especifican las operaciones que una entidad puede realizar en las tablas y vistas de ese conjunto de datos específico. Para obtener información sobre cómo configurar los controles de acceso a nivel de conjunto de datos, consulta Controla el acceso a los conjuntos de datos.

También puedes otorgar las funciones de Cloud IAM en un nivel superior en la jerarquía de recursos de Google Cloud, como el nivel de proyecto, de carpeta o de organización. Otorgar funciones en un nivel superior le da a la entidad acceso a un conjunto más amplio de recursos. Por ejemplo, otorgar una función a una entidad en el nivel de proyecto le brinda a esa entidad permisos que se aplican a todos los conjuntos de datos del proyecto. Para obtener más información sobre cómo otorgar acceso a los recursos, consulta la página sobre cómo otorgar, cambiar y revocar acceso a los recursos en la documentación de Cloud IAM.

También puedes crear funciones personalizadas de Cloud IAM. Si creas una función personalizada, los permisos que otorgas dependerán de las operaciones específicas que deseas que la entidad pueda realizar.

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

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

Cómo usar tablas particionadas

Cómo obtener información sobre tablas particionadas

Puedes obtener información sobre las tablas de las siguientes formas:

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

Permisos necesarios

Como mínimo, para obtener información sobre las vistas, 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, cuando crea un conjunto de datos, se le otorga el acceso bigquery.dataOwner. El acceso bigquery.dataOwner le otorga al usuario la capacidad de recuperar los metadatos de la tabla.

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

Cómo obtener información acerca de una tabla particionada

Para ver información sobre una tabla particionada, haz esto:

Console

Abre la IU web de BigQuery en Cloud Console.
Ir a la IU web de BigQuery
En el panel de navegación, en la sección Recursos (Resources), expande tu proyecto y conjunto de datos; luego, haz clic en el nombre de la tabla en la lista.
Haz clic en Detalles (Details) debajo del Editor de consultas. En esta pestaña se muestra la descripción de la tabla y la información de la tabla.
Haz clic en la pestaña Esquema para ver la definición del esquema de la tabla. Ten en cuenta que las tablas particionadas no incluyen la seudocolumna _PARTITIONTIME.

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. Esta acción muestra las tablas y vistas del conjunto de datos.
Haz clic en el nombre de la tabla.
Haz clic en Details (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 Esquema para ver la definición del esquema de la tabla. Ten en cuenta que las tablas particionadas no incluyen la seudocolumna _PARTITIONTIME.

CLI

Ejecuta el comando de 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. Se puede usar la marca --format para controlar el resultado.

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

bq show --schema --format=prettyjson project_id:dataset.table

Donde:

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 comando siguiente para mostrar toda la información sobre mytable en mydataset. mydataset está en tu proyecto predeterminado.

bq show --format=prettyjson mydataset.mytable

Ingresa el comando siguiente 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

El resultado debe verse de la siguiente manera:

{
  "creationTime": "1563236533535",
  "description": "This is my partitioned table",
  "etag": "/ABcDEo7f8GHijKL2mnOpQr==",
  "expirationTime": "1565828533000",
  "id": "myproject:mydataset.mypartitionedtable",
  "kind": "bigquery#table",
  "labels": {
    "org": "dev"
  },
  "lastModifiedTime": "1563236533576",
  "location": "US",
  "numBytes": "0",
  "numLongTermBytes": "0",
  "numRows": "0",
  "requirePartitionFilter": true,
  "schema": {
    "fields": [
      {
        "name": "ts",
        "type": "TIMESTAMP"
      },
      {
        "name": "column1",
        "type": "STRING"
      },
      {
        "name": "column2",
        "type": "INTEGER"
      },
      {
        "name": "column3",
        "type": "STRING"
      }
    ]
  },
  "selfLink": "https://bigquery.googleapis.com/bigquery/v2/projects/myproject/datasets/mydataset/tables/mypartitionedtable",
  "tableReference": {
    "datasetId": "mydataset",
    "projectId": "myproject",
    "tableId": "mypartitionedtable"
  },
  "timePartitioning": {
    "expirationMs": "86400000",
    "field": "ts",
    "requirePartitionFilter": true,
    "type": "DAY"
  },
  "type": "TABLE"
}

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.

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

El resultado debe verse de la siguiente manera:

[
  {
    "name": "ts",
    "type": "TIMESTAMP"
  },
  {
    "name": "column1",
    "type": "STRING"
  },
  {
    "name": "column2",
    "type": "INTEGER"
  },
  {
    "name": "column3",
    "type": "STRING"
  }
]

API

Realiza una llamada al método bigquery.tables.get y proporciona los parámetros relevantes.

Cómo mostrar una lista de las tablas particionadas en un conjunto de datos

Puedes enumerar las tablas en los conjuntos de datos (incluidas las tablas particionadas) de las siguientes maneras:

Mediante Cloud Console o la IU web clásica de BigQuery
Mediante el comando bq ls de la CLI
Con una llamada al método tables.list de la API
Con las bibliotecas cliente

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.dataEditor
bigquery.dataOwner
bigquery.admin

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

Cómo obtener una lista de tablas particionadas

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

Console

Abre la IU web de BigQuery en Cloud Console.
Ir a la IU web de BigQuery
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 diferentes íconos.

IU clásica

En la IU web de BigQuery, en el panel de navegación, haz clic en el ícono de flecha hacia abajo 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.

CLI

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

Donde:

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, en el campo Time Partitioning se muestra DAY, la columna que se usa a fin de crear las particiones y el vencimiento de la partición en milisegundos, si se especifica.

Por ejemplo:

+-------------------------+-------+----------------------+---------------------------------------------------+
|         tableId         | Type  |        Labels        | Time Partitioning                                 |
+-------------------------+-------+----------------------+---------------------------------------------------+
| mytable                 | TABLE | department:shipping  |  DAY (field: source_date, expirationMs: 86400000) |
| 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 enumerar tablas con la API, realiza una llamada al método tables.list.

Cómo mostrar la lista de particiones de tablas particionadas

A fin de mostrar la lista de particiones de una tabla particionada, puedes realizar una consulta en la metatabla __PARTITIONS_SUMMARY__ con 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

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.

Cómo ver la lista de particiones en una tabla particionada

Puedes enumerar las particiones de una tabla particionada mediante SQL heredado. Para hacerlo, sigue estos pasos:

Console

Abre la IU web de BigQuery en Cloud Console.
Ir a Cloud Console
Haz clic en el botón Redactar consulta nueva.
Ingresa el texto siguiente en el cuadro Editor de consulta para consultar la metatabla __PARTITIONS_SUMMARY__:
```
#legacySQL
SELECT
  partition_id
FROM
  [dataset.table$__PARTITIONS_SUMMARY__]
```
Donde:
- dataset es el conjunto de datos que contiene la tabla.
- table es el nombre de la tabla.
Haz clic en 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 texto siguiente en el cuadro Consulta nueva para consultar la metatabla __PARTITIONS_SUMMARY__:
```
#legacySQL
SELECT
  partition_id
FROM
  [dataset.table$__PARTITIONS_SUMMARY__]
```
Donde:
- dataset es el conjunto de datos que contiene la tabla.
- table es el nombre de la tabla.
Haz clic en Mostrar opciones.
Haz clic en Ejecutar consulta.

CLI

Ingresa la consulta siguiente con el comando bq query:

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

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, establece el valor de la marca en asia-northeast1. Puedes configurar un valor predeterminado para la ubicación con el archivo .bigqueryrc.
dataset.table es el conjunto de datos que contiene la tabla.
dataset.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__ de la tabla.

Cómo obtener metadatos de tabla particionada 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.

En este momento, no puedes usar el servicio INFORMATION_SCHEMA para obtener metadatos de tabla particionada.

Cómo obtener 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. Puedes ejecutar la consulta de la siguiente manera:

Mediante 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
Con las bibliotecas cliente

En este momento, SQL estándar no es compatible con el separador del decorador de particiones ($), 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__]

Donde:

dataset es el nombre de tu conjunto de datos.
table es el nombre de la tabla particionada por tiempo.
column es uno de los siguientes valores:

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, en milisegundos, desde el 1 de enero de 1970 UTC.
`last_modified_time`	El momento en que se modificó la partición por última vez, en milisegundos, desde el 1 de enero de 1970 UTC.

Permisos de metatablas de partición

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 luce de la manera siguiente:

+----------------+------------+----------------+--------------+---------------+--------------------+
|   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 luce de la manera siguiente:

+--------------+--------------------+
| 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 luce de la manera siguiente:

+--------------+----------------------------+
| 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 |
+--------------+----------------------------+

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 cómo crear y usar tablas particionadas por tiempo de transferencia, consulta esta página sobre cómo crear y usar tablas particionadas por tiempo de transferencia.
Para aprender a crear y usar tablas particionadas por rango de números enteros, consulta la página sobre cómo crear y usar tablas particionadas por rango de números enteros.
Para aprender a administrar y actualizar tablas particionadas, consulta Administra tablas con particiones.
Si deseas obtener información acerca de cómo consultar tablas particionadas, puedes leer Consulta tablas particionadas.

Limitaciones

Crea tablas particionadas

Nombres de las tablas

Permisos necesarios

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

Console

DDL

IU clásica

CLI

API

Go

Node.js

Python

Crea tablas particionadas a partir de los resultados de la consulta

Crea una tabla particionada a partir de un resultado de consulta

Console

IU clásica

CLI

API

Cómo crear una tabla particionada en el momento de cargar datos

Cómo controlar el acceso a las tablas particionadas

Cómo usar tablas particionadas

Cómo obtener información sobre tablas particionadas

Permisos necesarios

Cómo obtener información acerca de una tabla particionada

Console

IU clásica

CLI

API

Cómo mostrar una lista de las tablas particionadas en un conjunto de datos

Permisos necesarios

Cómo obtener una lista de tablas particionadas

Console

IU clásica

CLI

API

Cómo mostrar la lista de particiones de tablas particionadas

Permisos necesarios

Cómo ver la lista de particiones en una tabla particionada

Console

IU clásica

CLI

API

Cómo obtener metadatos de tabla particionada con metatablas

Cómo obtener metadatos de partición con metatablas

Permisos de metatablas de partición

Ejemplos de metatablas de partición

Console

IU clásica

CLI

Console

IU clásica

CLI

Console

IU clásica

CLI

Próximos pasos

Enviar comentarios sobre...