Administra tablas particionadas

En este documento, se describe cómo administrar tablas particionadas en BigQuery. Las tablas particionadas y las particionadas por tiempo de transferencia se administran de la misma manera. Puedes realizar las siguientes tareas de administración para las tablas particionadas:

  • Actualizar los siguientes elementos de una tabla particionada por tiempo:
    • Descripción
    • Tiempo de vencimiento de la tabla
    • Tiempo de vencimiento de la partición
    • Requisitos del filtro de partición
    • Definición de esquema
    • Etiquetas
  • Volver a nombrar (copiar) una tabla con particiones por tiempo
  • Copiar una tabla particionada por tiempo
  • Copiar particiones
  • Borrar una tabla particionada por tiempo
  • Borrar particiones en una tabla particionada por tiempo

Para obtener más información sobre cómo crear y usar tablas particionadas, incluida la información sobre tablas, su generación y el control de acceso a sus datos, consulta Crea y usa tablas particionadas por tiempo de transferencia o cómo crear y usar tablas particionadas.

Actualiza las propiedades de la tabla particionada

Puedes actualizar los siguientes elementos de una tabla con particiones:

  • Descripción
  • Tiempo de vencimiento de la tabla
  • Tiempo de vencimiento de la partición
  • Definición de esquema
  • Etiquetas

Permisos necesarios

Para actualizar las propiedades de la tabla, debes tener los permisos bigquery.tables.update y bigquery.tables.get como mínimo. Las siguientes funciones predefinidas de Cloud IAM incluyen los permisos bigquery.tables.update y bigquery.tables.get:

  • bigquery.dataEditor
  • bigquery.dataOwner
  • 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 permite que el usuario actualice las propiedades de las tablas en ese 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.

Actualiza la descripción de una tabla particionada

El proceso para actualizar la descripción de una tabla particionada es el mismo que el de actualizar la descripción de una tabla estándar. Para obtener más información sobre cómo agregar o cambiar la descripción de una tabla, consulta cómo actualizar la descripción de una tabla.

Actualmente, no puedes crear descripciones de particiones individuales.

Actualiza el vencimiento de la tabla

El proceso para actualizar del vencimiento de una tabla particionada es el mismo que el de actualizar el vencimiento de una tabla estándar. Para obtener más información sobre cómo agregar o cambiar el vencimiento de una tabla, consulta Cómo actualizar el tiempo de vencimiento de una tabla.

Actualiza el vencimiento de la partición

Puedes especificar el vencimiento de la partición para una tabla particionada cuando la tabla se crea de la siguiente manera:

  • Mediante una declaración DDL ALTER TABLE
  • Mediante el comando bq mk de la herramienta de línea de comandos
  • Mediante una llamada al método tables.insert de la API
  • Mediante bibliotecas cliente

Actualmente, Cloud Console o la IU web clásica de BigQuery no admiten la especificación del vencimiento de la partición.

Si especificas el vencimiento de una partición cuando creas una tabla, este anula el vencimiento de partición predeterminado a nivel de conjunto de datos. Cuando configures un vencimiento de partición a nivel de tabla, todas las particiones estarán sujetas al vencimiento. No puedes aplicar otras horas de vencimiento a particiones individuales.

Después de crear la tabla, puedes actualizar la hora de vencimiento de la partición en cualquier momento, mediante el comando bq update de la CLI o el método tables.patch de la API. Actualmente, Cloud Console o la IU web clásica de BigQuery no admiten la actualización del vencimiento de la partición. Sin embargo, puedes usar una declaración DDL para actualizar el vencimiento de la partición en cualquier IU.

Cuando actualizas el vencimiento de la partición de una tabla, la configuración se aplica a todas las particiones, independientemente de cuándo se crearon.

Cuando actualizas la fecha de vencimiento de la partición de una tabla, debes calcular el vencimiento de la partición desde la medianoche UTC para la fecha de la partición.

Si la tabla particionada también tiene establecido un vencimiento de tabla, esta y todas sus particiones se borrarán según la configuración de vencimiento de la tabla. El vencimiento de la tabla tiene prioridad sobre el vencimiento de la partición.

Por ejemplo, si el vencimiento de una tabla particionada se configura a 5 días y el tiempo de vencimiento de la partición se configura a 7 días, la tabla y todas sus particiones se borrarán después de 5 días.

Para los proyectos que tengan tablas particionadas que se crearon antes del 13 de diciembre de 2016, el vencimiento de la partición se basa en la última fecha en que se modificó la partición. Este comportamiento también se aplica a las tablas nuevas que se crearon en estos proyectos. Para migrar tu proyecto al comportamiento nuevo, abre una solicitud en el seguimiento de problemas de BigQuery.

Para actualizar el vencimiento de la partición de una tabla con particiones, sigue estos pasos:

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.

Para obtener más información, consulta la página sobre cómo usar instrucciones del lenguaje de definición de datos.

Para actualizar el vencimiento de la partición de una tabla particionada mediante una declaración del DDL, realiza los siguientes pasos:

  1. Abre la IU web de BigQuery en Cloud Console.
    Ir a Cloud Console

  2. Haz clic en Redactar consulta nueva.

  3. Escribe tu declaración del DDL en el área de texto Editor de consultas.

     ALTER TABLE mydataset.mytable
     SET OPTIONS (
       -- Sets partition expiration to 5 days
       partition_expiration_days=5
     )
     

  4. Haz clic en Ejecutar.

CLI

Ejecuta el comando bq update con la marca --time_partitioning_expiration. Si actualizas una tabla particionada en un proyecto que no es tu proyecto predeterminado, debes agregar el ID del proyecto al nombre del conjunto de datos en el formato siguiente: project_id:dataset.

bq update \
--time_partitioning_expiration integer \
project_id:dataset.table

En el ejemplo anterior, se ilustra lo siguiente:

  • integer es el ciclo de vida predeterminado (en segundos) de las particiones de la tabla. No hay valor mínimo. La hora de vencimiento se evalúa según la fecha en la que se encuentre la partición más el valor de número entero. Si especificas 0, el vencimiento de la partición se quitará y la partición nunca vencerá. Las particiones sin vencimiento deben borrarse de forma manual.
  • project_id es el ID del proyecto.
  • dataset es el nombre del conjunto de datos que contiene la tabla que quieres actualizar.
  • table es el nombre de la tabla que quieres actualizar.

Ejemplos:

Ingresa el comando siguiente para actualizar la fecha de vencimiento de las particiones en mydataset.mytable a 5 días (432,000 segundos). mydataset está en tu proyecto predeterminado.

bq update --time_partitioning_expiration 432000 mydataset.mytable

Ingresa el comando siguiente para actualizar la fecha de vencimiento de las particiones en mydataset.mytable a 5 días (432,000 segundos). mydataset se encuentra en myotherproject, no en tu proyecto predeterminado.

bq update \
--time_partitioning_expiration 432000 \
myotherproject:mydataset.mytable

API

Llama al método tables.patch y usa la propiedad timePartitioning.expirationMs para actualizar el vencimiento de la partición en milésimas de segundo. Debido a que, con el método tables.update se reemplaza todo el recurso de tabla, es preferible usar el método tables.patch.

Actualiza los requisitos del filtro de partición

Cuando creas una tabla particionada, puedes exigir el uso de filtros predicados si habilitas la opción Exigir filtro de partición. Cuando se aplica esta opción, los intentos de consultar la tabla particionada sin especificar una cláusula WHERE producen el siguiente error: Cannot query over table 'project_id.dataset.table' without a filter that can be used for partition elimination.

Para obtener más información sobre cómo agregar la opción Exigir filtro de partición cuando creas una tabla particionada, consulta Crea tablas particionadas.

Si no habilitas la opción Exigir filtro de partición cuando creas una tabla particionada, puedes actualizar la tabla para agregar la opción.

Actualiza la opción Exigir filtro de partición

Para actualizar una tabla particionada a fin de requerir consultas que contienen una cláusula WHERE que reduce las particiones, realiza los siguientes pasos:

Console

No puedes usar Cloud Console para exigir filtros de partición después de crear una tabla particionada.

IU clásica

No puedes usar la IU web para requerir filtros de partición después de crear una tabla particionada.

CLI

Para actualizar una tabla particionada a fin de exigir filtros de partición mediante la CLI, ingresa el comando bq update y proporciona la marca --require_partition_filter.

Para actualizar una tabla particionada en un proyecto que no sea tu proyecto predeterminado, agrega el ID del proyecto al conjunto de datos con el siguiente formato: project_id:dataset.

Por ejemplo:

Para actualizar mypartitionedtable en mydataset en tu proyecto predeterminado, ingresa el siguiente código:

bq update --require_partition_filter mydataset.mytable

Para actualizar mypartitionedtable en mydataset en myotherproject, ingresa el siguiente código:

bq update --require_partition_filter myotherproject:mydataset.mytable

API

Llama al método tables.patch y establece la propiedad requirePartitionFilter en true para exigir filtros de partición. Debido a que, con el método tables.update se reemplaza todo el recurso de tabla, es preferible usar el método tables.patch.

Actualiza la definición de esquema

Para actualizar la definición de esquema de una tabla particionada, se realiza el mismo proceso que con una tabla estándar. Para obtener más información, consulta Modifica esquemas de tabla.

Cambia el nombre de una tabla particionada

Actualmente, no puedes cambiar el nombre de una tabla particionada existente. Si es necesario cambiar el nombre de la tabla, sigue los pasos para copiar la tabla. Usa el nombre nuevo de la tabla cuando especifiques la tabla de destino en la operación de copia.

Copiar tablas particionadas

Copia una tabla particionada única

El proceso para copiar una tabla particionada y una tabla estándar es el mismo. Para obtener más información, consulta Cómo copiar una tabla.

Cuando copies una tabla particionada, ten en cuenta lo siguiente:

  • Las tablas de origen y destino deben estar en conjuntos de datos en la misma ubicación.

  • Copiar una tabla particionada en una tabla de destino particionada nueva
    Si copias una tabla particionada por tiempo a una tabla nueva, toda la información de partición se copia con la tabla. La tabla nueva y la anterior tendrán particiones idénticas.
  • Copiar una tabla no particionada en una tabla particionada
    Si copias una tabla no particionada en una tabla particionada, BigQuery copia los datos de origen en la partición que representa la fecha actual.
  • Copiar una tabla particionada en otra tabla particionada
    Para copiar una tabla particionada en otra, las especificaciones de partición de las tablas de origen y destino deben coincidir. Puedes especificar si deseas agregar o reemplazar la tabla de destino.
  • Copiar una tabla particionada en una tabla no particionada
    Si copias una tabla particionada a una tabla no particionada, la tabla de destino permanece sin particiones. Según tu configuración, los datos se agregan a la tabla no particionada o se usan para reemplazarla.

Copia varias tablas particionadas

El proceso para copiar varias tablas particionadas y varias tablas estándar es el mismo. Para obtener más información, consulta Cómo copiar varias tablas de origen.

Cuando copies varias tablas con particiones, ten en cuenta lo siguiente:

  • Si copias varias tablas de origen en una tabla con particiones en el mismo trabajo, las tablas de origen no podrán contener una mezcla de tablas con particiones y sin particiones.
  • Si todas las tablas de origen son tablas particionadas, sus especificaciones de partición deben coincidir con la especificación de partición de la tabla de destino. Tu configuración determina si la tabla de destino se agrega o se reemplaza.
  • Las tablas de origen y destino deben estar en conjuntos de datos en la misma ubicación.

Copia particiones

Para copiar una o más particiones, sigue estos pasos:

  • Usa el comando bq cp de la herramienta de línea de comandos.
  • Llama al método jobs.insert de la API y configura un trabajo copy.
  • Usa bibliotecas cliente

Actualmente, Cloud Console o la IU web clásica de BigQuery no admiten la copia de particiones.

Permisos necesarios

Como mínimo, para copiar tablas y particiones, debes tener los siguientes permisos:

En el conjunto de datos de origen:

  • bigquery.tables.get
  • bigquery.tables.getData

En el conjunto de datos de destino:

  • bigquery.tables.create para crear la copia de la tabla o partición en el conjunto de datos de destino

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

  • bigquery.dataEditor
  • bigquery.dataOwner
  • bigquery.admin

Además, para ejecutar el trabajo de copia, 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

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 a bigquery.dataOwner otorga al usuario la capacidad de copiar tablas y particiones en el conjunto de datos, pero se requiere acceso al conjunto de datos de destino, a menos que el usuario haya creado el conjunto de datos de destino.

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

Copia una partición única

Console

Cloud Console no admite la copia de particiones.

IU clásica

La IU web clásica de BigQuery no admite la copia de particiones.

CLI

Usa el comando bq cp (copia) de la herramienta de línea de comandos para copiar una partición con un decorador de particiones ($date), como $20160201.

Se pueden usar marcas opcionales para controlar la disposición de escritura de la partición de destino:

  • -a o --append_table anexan los datos de las particiones de origen a una tabla o partición existente en el conjunto de datos de destino.
  • -f o --force reemplaza una tabla o partición existente en el conjunto de datos de destino y no te solicitará confirmación.
  • -n o --no_clobber muestran el siguiente mensaje de error si la tabla o partición ya existe en el conjunto de datos de destino: Table '<var>project_id:dataset.table</var> or <var>table$date</var>' already exists, skipping. Si no se especifica , el comportamiento predeterminado es solicitarte confirmación para reemplazar la tabla de destino o la de partición.
  • --destination_kms_key es la clave de Cloud KMS administrada por el cliente que se usa para encriptar la tabla o partición de destino.

El comando cp no admite las marcas --time_partitioning_field o --time_partitioning_type. No puedes usar un trabajo de copia para convertir una tabla particionada por tiempo de transferencia en una tabla particionada.

--destination_kms_key no se muestra aquí. Para obtener más información, consulta la página sobre cómo proteger datos con claves de Cloud KMS.

Si el conjunto de datos de origen o de destino se encuentra en un proyecto que no es el predeterminado, debes agregar el ID del proyecto a los nombres de los conjuntos de datos con el siguiente formato: project_id:dataset.

Opcional: Proporciona la marca --location y configura el valor en tu ubicación.

bq --location=location cp \
-a -f -n \
project_id:dataset.source_table$source_partition \
project_id:dataset.destination_table$destination_partition

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 con el archivo .bigqueryrc.
  • project_id es el ID del proyecto.
  • dataset es el nombre del conjunto de datos de origen o de destino.
  • source_table es la tabla que quieres copiar.
  • source_partition es el decorador de particiones de la partición de origen.
  • destination_table es el nombre de la tabla en el conjunto de datos de destino.
  • destination_partition es el decorador de particiones de la partición de destino.

Ejemplos:

Copia una partición a una tabla nueva

Ingresa el siguiente comando para copiar la partición del 30 de enero de 2018 desde mydataset.mytable a la nueva tabla, mydataset.mytable2. mydataset está en tu proyecto predeterminado.

bq cp -a 'mydataset.mytable$20180130' mydataset.mytable2

Copia una partición a una tabla no particionada

Ingresa el siguiente comando para copiar la partición del 30 de enero de 2018 desde mydataset.mytable a una tabla no particionada, mydataset2.mytable2. Se usa la combinación de teclas -a para agregar los datos de la partición a la tabla de destino no particionada. Ambos conjuntos de datos se encuentran en tu proyecto predeterminado.

bq cp -a 'mydataset.mytable$20180130' mydataset2.mytable2

Ingresa el siguiente comando para copiar la partición del 30 de enero de 2018 desde mydataset.mytable a una tabla no particionada, mydataset2.mytable2. Se usa la combinación de teclas -f para reemplazar la tabla de destino no particionada sin solicitarla.

bq --location=US cp -f 'mydataset.mytable$20180130' mydataset2.mytable2

Copia una partición a otra tabla particionada

Ingresa el siguiente comando para copiar la partición del 30 de enero de 2018 desde mydataset.mytable a otra tabla particionada, mydataset2.mytable2. Se usa la combinación de teclas -a para agregar los datos de la partición a la tabla de destino. Ya que no se especifica ningún decorador de particiones en la tabla de destino, la clave de partición de origen se conserva y los datos se copian a la partición del 30 de enero de 2018 en la tabla de destino. También puedes especificar un decorador de particiones en la tabla de destino para copiar datos a la partición específica. mydataset está en tu proyecto predeterminado. mydataset2 está en myotherproject, no en tu proyecto predeterminado.

bq --location=US cp \
-a \
'mydataset.mytable$20180130' \
myotherproject:mydataset2.mytable2

Ingresa el siguiente comando para copiar la partición del 30 de enero de 2018 desde mydataset.mytable a la partición del 20 de febrero de 2018 de otra tabla particionada, mydataset2.mytable2. Se usa la combinación de teclas -f para reemplazar la partición del 20 de febrero de 2018 en la tabla de destino sin solicitarla. Si no se utiliza un decorador de particiones, se reemplazan todos los datos en la tabla de destino. mydataset está en tu proyecto predeterminado. mydataset2 está en myotherproject, no en tu proyecto predeterminado.

bq cp \
-f \
'mydataset.mytable$20180130' \
'myotherproject:mydataset2.mytable2$20180220'

Ingresa el siguiente comando para copiar la partición del 30 de enero de 2018 desde mydataset.mytable a otra tabla particionada, mydataset2.mytable2. mydataset está en tu proyecto predeterminado. mydataset2 está en myotherproject, no en tu proyecto predeterminado. Si hay datos en la tabla de destino, el comportamiento predeterminado es solicitarte que los reemplaces.

bq cp \
'mydataset.mytable$20180130' \
myotherproject:mydataset2.mytable2

API

Llama al método jobs.insert y configura un trabajo copy. Opcional: Especifica tu región en la propiedad location de la sección jobReference del recurso de trabajo.

Especifica las siguientes propiedades en la configuración de tu trabajo:

  • Ingresa la tabla, la partición y el conjunto de datos de origen en la propiedad sourceTables.
  • Ingresa el conjunto de datos y la tabla de destino en la propiedad destinationTable.
  • Usa la propiedad writeDisposition para especificar si deseas agregar o reemplazar la tabla o partición de destino.

Copia varias particiones

Si deseas copiar varias particiones, ten en cuenta lo siguiente:

Console

Actualmente, Cloud Console no admite la copia de particiones.

IU clásica

En la actualidad, la IU web clásica de BigQuery no admite la copia de particiones.

CLI

Copiar varias particiones es el mismo proceso que copiar una partición única, pero tienes que especificar varias particiones de origen como una lista separada por comas:

bq cp \
'mydataset.mytable$20180130,mydataset.mytable$20180131' \
myotherproject:mydataset.mytable2

API

Llama al método jobs.insert y configura un trabajo copy. Especifica tu región en la propiedad location en la sección jobReference del recurso de trabajo.

Especifica las siguientes propiedades en la configuración de tu trabajo:

  • Ingresa varias particiones de origen (incluidos los nombres del conjunto de datos y de la tabla) en la propiedad sourceTables.
  • Ingresa el conjunto de datos y la tabla de destino en la propiedad destinationTable.
  • Usa la propiedad writeDisposition para especificar si deseas agregar o reemplazar la tabla o partición de destino.

Borra una tabla particionada

El proceso para borrar una tabla particionada por tiempo y todas las particiones que contenga es el mismo que el de borrar una tabla estándar. Para obtener más información sobre cómo borrar una tabla, consulta Cómo borrar tablas.

Borra particiones en tablas particionadas

Puedes borrar particiones en tablas particionadas con el comando bq rm de la herramienta de línea de comandos o con una llamada al método tables.delete de la API. Actualmente, la IU web clásica de BigQuery no admite que se borren particiones.

Puedes usar el decorador de particiones para borrar una partición específica. Por ejemplo, la partición del 1 de marzo de 2016 ($20160301) en una tabla particionada llamada mydataset.mytable se puede borrar con el siguiente comando:

bq rm 'mydataset.mytable$20160301'

Para recuperar una lista de particiones en una tabla particionada, consulta Crea una lista de particiones en tablas particionadas por tiempo de transferencia o cómo mostrar la lista de particiones de tablas particionadas.

Actualmente, solo puedes borrar una partición a la vez.

Permisos necesarios

Para borrar una partición, debes tener los permisos bigquery.tables.delete y bigquery.tables.get como mínimo. Las siguientes funciones predefinidas de Cloud IAM incluyen los permisos bigquery.tables.delete y bigquery.tables.get:

  • 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 le proporciona al usuario la capacidad de borrar tablas y particiones 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.

Borra una partición en una tabla particionada

Puedes borrar una partición si especificas el decorador de la partición, a menos que sea una de las dos particiones especiales. Actualmente, no puedes borrar las particiones __NULL__ o __UNPARTITIONED__.

Ten en cuenta lo siguiente para borrar una partición en una tabla particionada:

Console

Cloud Console no admite que se borren particiones.

IU clásica

La IU web clásica de BigQuery no admite que se borren particiones.

CLI

Para borrar una partición específica en una tabla particionada, usa el comando bq rm con la marca --table (o la combinación de teclas -t) y haz referencia al decorador de particiones ($date). Cuando uses la CLI para quitar una partición, debes confirmar la acción. Puedes usar la marca --force (o la combinación de teclas -f) para omitir la confirmación.

Si la tabla particionada se encuentra en un conjunto de datos en un proyecto que no es el predeterminado, debes agregar el ID del proyecto al nombre del conjunto de datos con el formato siguiente: project_id:dataset.

bq rm -f -t project_id:dataset.table$date

En el ejemplo anterior, se ilustra lo siguiente:

  • project_id es el ID del proyecto.
  • dataset es el nombre del conjunto de datos que contiene la tabla.
  • table es el nombre de la tabla.
  • $date es el decorador de particiones de la partición que borras.

Ejemplos:

Ingresa el siguiente comando para borrar la partición del 1 de marzo de 2016 ($20160301) en una tabla particionada llamada mydataset.mytable. mydataset está en tu proyecto predeterminado.

bq rm 'mydataset.mytable$20160301'

Ingresa el siguiente comando para borrar la partición del 1 de enero de 2017 ($20170101) en una tabla particionada llamada mydataset.mytable. mydataset está en myotherproject, no en tu proyecto predeterminado.

bq rm 'myotherproject:mydataset.mytable$20170101'

Ingresa el siguiente comando para borrar la partición del 18 de enero de 2018 ($20180118) en una tabla particionada llamada mydataset.mytable. mydataset está en myotherproject, no en tu proyecto predeterminado. La combinación de teclas -f se usa para omitir la confirmación.

bq rm -f 'myotherproject:mydataset.mytable$20180118'

API

Llama al método tables.delete y especifica la tabla y el decorador de particiones con el parámetro tableId.