Crea tablas particionadas

En esta página, se describe cómo crear tablas particionadas en BigQuery. Para ver una descripción general de las tablas particionadas, consulta Introducción a las tablas particionadas.

Antes de comenzar

Otorga funciones de Identity and Access Management (IAM) que les brindan a los usuarios los permisos necesarios para realizar cada tarea de este documento.

Permisos necesarios

Para crear una tabla, necesitas los siguientes permisos de IAM:

  • bigquery.tables.create
  • bigquery.tables.updateData
  • bigquery.jobs.create

Además, es posible que necesites el permiso bigquery.tables.getData para acceder a los datos que escribas en la tabla.

Cada una de las siguientes funciones predefinidas de IAM incluye los permisos que necesitas para crear una tabla:

  • roles/bigquery.dataEditor
  • roles/bigquery.dataOwner
  • roles/bigquery.admin (incluye el permiso bigquery.jobs.create)
  • roles/bigquery.user (incluye el permiso bigquery.jobs.create)
  • roles/bigquery.jobUser (incluye el permiso bigquery.jobs.create)

Además, si tienes el permiso bigquery.datasets.create, puedes crear y actualizar tablas en los conjuntos de datos que crees.

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

Crea una tabla particionada vacía

Los pasos para crear una tabla particionada en BigQuery son similares a crear una tabla estándar, salvo que especificas las opciones de partición, junto con cualquier otra opción de tabla.

Crea una tabla particionada por columnas de unidad de tiempo

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

Console

  1. En la consola de Google Cloud, ve a la página de BigQuery.

    Ir a BigQuery

  2. En el panel Explorador, expande tu proyecto y, luego, elige un conjunto de datos.
  3. En la sección Información del conjunto de datos, haz clic en Crear tabla.
  4. En el panel Crear tabla, especifica los siguientes detalles:
    1. En la sección Fuente, selecciona Tabla vacía en la lista Crear tabla desde.
    2. En la sección Destino, especifica los siguientes detalles:
      1. En Conjunto de datos, elige el conjunto de datos en el que deseas crear la tabla.
      2. En el campo Tabla, escribe el nombre de la tabla que deseas crear.
      3. Verifica que el campo Tipo de tabla esté configurado como Tabla nativa.
    3. En la sección Esquema, ingresa la definición del esquema. El esquema debe incluir una columna DATE, TIMESTAMP o DATETIME para la columna de partición. Si deseas obtener más información, consulta Especifica un esquema. Puedes ingresar la información del esquema de forma manual mediante uno de los siguientes métodos:
      • Opción 1: Haz clic en Editar como texto y pega el esquema con el formato de un array JSON. Cuando usas un array JSON, generas el esquema mediante el mismo proceso que se usa para crear un archivo de esquema JSON. Puedes ver el esquema de una tabla existente en formato JSON si ingresas el siguiente comando:
            bq show --format=prettyjson dataset.table
            
      • Opción 2: Haz clic en Agregar campo y, luego, ingresa el esquema de la tabla. Especifica el Nombre, el Tipo y el Modo de cada campo.
    4. En la sección Configuración de particiones y clústeres, en la lista Partición, selecciona Partición por campo y, luego, elige la columna de partición. Esta opción solo está disponible si el esquema contiene una columna DATE, TIMESTAMP o DATETIME.
    5. Opcional: A fin de solicitar un filtro de partición en todas las consultas de esta tabla, selecciona la casilla de verificación Exigir filtro de partición. Un filtro de partición puede reducir los costos y mejorar el rendimiento. Si deseas obtener más información, consulta Configura requisitos para filtros de partición.
    6. Selecciona el Tipo de partición para elegir la partición por día, hora, mes o año.
    7. Opcional: En la sección Opciones avanzadas, si deseas usar una clave de encriptación administrada por el cliente, selecciona la opción Usar una clave de encriptación administrada por el cliente (CMEK). De forma predeterminada, BigQuery encripta contenido de clientes almacenado en reposo mediante una clave administrada por Google.
    8. Haga clic en Crear tabla.

SQL

Para crear una tabla particionada por columnas de unidad de tiempo, usa la declaración DDL CREATE TABLE con una cláusula PARTITION BY.

En el siguiente ejemplo, se crea una tabla con particiones por día en función de la columna transaction_date:

  1. En la consola de Google Cloud, ve a la página de BigQuery.

    Ir a BigQuery

  2. En el editor de consultas, ingresa la siguiente sentencia:

    CREATE TABLE
      mydataset.newtable (transaction_id INT64, transaction_date DATE)
    PARTITION BY
      transaction_date
      OPTIONS (
        partition_expiration_days = 3,
        require_partition_filter = TRUE);
    

    Usa la cláusula OPTIONS para configurar opciones de tabla como el vencimiento de la partición y los requisitos del filtro de partición.

  3. Haz clic en Ejecutar.

Si deseas obtener información sobre cómo ejecutar consultas, visita Ejecuta una consulta interactiva.

El tipo de partición predeterminado para las columnas DATE es la partición por día. Si deseas especificar un tipo de partición diferente, incluye la función DATE_TRUNC en la cláusula PARTITION BY. Por ejemplo, con la siguiente consulta, se crea una tabla con particiones por mes:

CREATE TABLE
  mydataset.newtable (transaction_id INT64, transaction_date DATE)
PARTITION BY
  DATE_TRUNC(transaction_date, MONTH)
  OPTIONS (
    partition_expiration_days = 3,
    require_partition_filter = TRUE);

También puedes especificar una columna TIMESTAMP o DATETIME como columna de partición. En ese caso, incluye la función TIMESTAMP_TRUNC o DATETIME_TRUNC en la cláusula PARTITION BY a fin de especificar el tipo de partición. Por ejemplo, la siguiente instrucción crea una tabla con particiones por día basadas en una columna TIMESTAMP:

CREATE TABLE
  mydataset.newtable (transaction_id INT64, transaction_ts TIMESTAMP)
PARTITION BY
  TIMESTAMP_TRUNC(transaction_ts, DAY)
  OPTIONS (
    partition_expiration_days = 3,
    require_partition_filter = TRUE);

bq

  1. En la consola de Google Cloud, activa Cloud Shell.

    Activar Cloud Shell

    En la parte inferior de la consola de Google Cloud, se inicia una sesión de Cloud Shell en la que se muestra una ventana de línea de comandos. Cloud Shell es un entorno de shell con Google Cloud CLI ya instalada y con valores ya establecidos para el proyecto actual. La sesión puede tardar unos segundos en inicializarse.

  2. Usa el comando bq mk con la marca --table (o la combinación de teclas -t):

    bq mk \
       --table \
       --schema SCHEMA \
       --time_partitioning_field COLUMN \
       --time_partitioning_type UNIT_TIME \
       --time_partitioning_expiration EXPIRATION_TIME \
       --require_partition_filter=BOOLEAN
       PROJECT_ID:DATASET.TABLE
    

    Reemplaza lo siguiente:

    • SCHEMA: una definición de esquema en el formato column:data_type,column:data_type o la ruta a un archivo de esquema JSON en tu máquina local. Si deseas obtener más información, consulta Especifica un esquema.
    • COLUMN: el nombre de la columna de partición. En el esquema de la tabla, esta columna debe ser de tipo TIMESTAMP, DATETIME o DATE.
    • UNIT_TIME: el tipo de partición. Entre los valores admitidos, se encuentran los siguientes DAY, HOUR, MONTH o YEAR.
    • EXPIRATION_TIME: el tiempo de vencimiento de las particiones de la tabla, en segundos. La marca --time_partitioning_expiration es opcional. Para obtener más información, consulta Configura el vencimiento de la partición.
    • BOOLEAN: Si es true, entonces las consultas de esta tabla deben incluir un filtro de partición. La marca --require_partition_filter es opcional. Si deseas obtener más información, consulta Configura requisitos para filtros de partición.
    • PROJECT_ID: El ID del proyecto Si se omite, se usa tu proyecto predeterminado.
    • DATASET: el nombre de un conjunto de datos en tu proyecto.
    • TABLE es el nombre de la tabla que se creará.

    Para obtener más opciones de línea de comandos, consulta bq mk.

    En el siguiente ejemplo, se crea una tabla llamada mytable que se particiona en la columna ts mediante la partición por hora. El vencimiento de la partición es de 259,200 segundos (3 días).

    bq mk \
       -t \
       --schema 'ts:TIMESTAMP,qtr:STRING,sales:FLOAT' \
       --time_partitioning_field ts \
       --time_partitioning_type HOUR \
       --time_partitioning_expiration 259200  \
       mydataset.mytable
    

Terraform

Usa el recurso google_bigquery_table.

En el siguiente ejemplo, se crea una tabla llamada mytable que se particiona por día:

resource "google_bigquery_dataset" "default" {
  dataset_id                      = "mydataset"
  default_partition_expiration_ms = 2592000000  # 30 days
  default_table_expiration_ms     = 31536000000 # 365 days
  description                     = "dataset description"
  location                        = "US"
  max_time_travel_hours           = 96 # 4 days

  labels = {
    billing_group = "accounting",
    pii           = "sensitive"
  }
}

resource "google_bigquery_table" "default" {
  dataset_id          = google_bigquery_dataset.default.dataset_id
  table_id            = "mytable"
  deletion_protection = false # set to "true" in production

  time_partitioning {
    type          = "DAY"
    field         = "Created"
    expiration_ms = 432000000 # 5 days
  }
  require_partition_filter = true

  schema = <<EOF
[
  {
    "name": "ID",
    "type": "INT64",
    "mode": "NULLABLE",
    "description": "Item ID"
  },
  {
    "name": "Created",
    "type": "TIMESTAMP",
    "description": "Record creation timestamp"
  },
  {
    "name": "Item",
    "type": "STRING",
    "mode": "NULLABLE"
  }
]
EOF

}

Para aplicar tu configuración de Terraform en un proyecto de Google Cloud, completa los pasos de las siguientes secciones.

Prepara Cloud Shell

  1. Inicia Cloud Shell
  2. Establece el proyecto de Google Cloud predeterminado en el que deseas aplicar tus configuraciones de Terraform.

    Solo necesitas ejecutar este comando una vez por proyecto y puedes ejecutarlo en cualquier directorio.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Las variables de entorno se anulan si configuras valores explícitos en el archivo de configuración de Terraform.

Prepara el directorio

Cada archivo de configuración de Terraform debe tener su propio directorio (también llamado módulo raíz).

  1. En Cloud Shell, crea un directorio y un archivo nuevo dentro de ese directorio. El nombre del archivo debe tener la extensión .tf, por ejemplo, main.tf. En este instructivo, el archivo se denomina main.tf.
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf
  2. Si sigues un instructivo, puedes copiar el código de muestra en cada sección o paso.

    Copia el código de muestra en el main.tf recién creado.

    De manera opcional, copia el código de GitHub. Esto se recomienda cuando el fragmento de Terraform es parte de una solución de extremo a extremo.

  3. Revisa y modifica los parámetros de muestra que se aplicarán a tu entorno.
  4. Guarda los cambios.
  5. Inicialice Terraform. Solo debes hacerlo una vez por directorio.
    terraform init

    De manera opcional, incluye la opción -upgrade para usar la última versión del proveedor de Google:

    terraform init -upgrade

Aplica los cambios

  1. Revisa la configuración y verifica que los recursos que creará o actualizará Terraform coincidan con tus expectativas:
    terraform plan

    Corrige la configuración según sea necesario.

  2. Para aplicar la configuración de Terraform, ejecuta el siguiente comando y, luego, escribe yes cuando se te solicite:
    terraform apply

    Espera hasta que Terraform muestre el mensaje “¡Aplicación completa!”.

  3. Abre tu proyecto de Google Cloud para ver los resultados. En la consola de Google Cloud, navega a tus recursos en la IU para asegurarte de que Terraform los haya creado o actualizado.

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 para Go incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Go.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

import (
	"context"
	"fmt"
	"time"

	"cloud.google.com/go/bigquery"
)

// createTablePartitioned demonstrates creating a table and specifying a time partitioning configuration.
func createTablePartitioned(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydatasetid"
	// tableID := "mytableid"
	ctx := context.Background()

	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	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
	}
	return nil
}

Java

Antes de probar este ejemplo, sigue las instrucciones de configuración para Java incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Java.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.StandardTableDefinition;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableInfo;
import com.google.cloud.bigquery.TimePartitioning;

// Sample to create a partition table
public class CreatePartitionedTable {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    Schema schema =
        Schema.of(
            Field.of("name", StandardSQLTypeName.STRING),
            Field.of("post_abbr", StandardSQLTypeName.STRING),
            Field.of("date", StandardSQLTypeName.DATE));
    createPartitionedTable(datasetName, tableName, schema);
  }

  public static void createPartitionedTable(String datasetName, String tableName, Schema schema) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);

      TimePartitioning partitioning =
          TimePartitioning.newBuilder(TimePartitioning.Type.DAY)
              .setField("date") //  name of column to use for partitioning
              .setExpirationMs(7776000000L) // 90 days
              .build();

      StandardTableDefinition tableDefinition =
          StandardTableDefinition.newBuilder()
              .setSchema(schema)
              .setTimePartitioning(partitioning)
              .build();
      TableInfo tableInfo = TableInfo.newBuilder(tableId, tableDefinition).build();

      bigquery.create(tableInfo);
      System.out.println("Partitioned table created successfully");
    } catch (BigQueryException e) {
      System.out.println("Partitioned table was not created. \n" + e.toString());
    }
  }
}

Node.js

Antes de probar este ejemplo, sigue las instrucciones de configuración para Node.js incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Node.js.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function createTablePartitioned() {
  // Creates a new partitioned table named "my_table" in "my_dataset".

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = "my_dataset";
  // const tableId = "my_table";
  const schema = 'Name:string, Post_Abbr:string, Date:date';

  // For all options, see https://cloud.google.com/bigquery/docs/reference/v2/tables#resource
  const options = {
    schema: schema,
    location: 'US',
    timePartitioning: {
      type: 'DAY',
      expirationMS: '7776000000',
      field: 'date',
    },
  };

  // Create a new table in the dataset
  const [table] = await bigquery
    .dataset(datasetId)
    .createTable(tableId, options);
  console.log(`Table ${table.id} created with partitioning: `);
  console.log(table.metadata.timePartitioning);
}

Python

Antes de probar este ejemplo, sigue las instrucciones de configuración para Python incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Python.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

from google.cloud import bigquery

client = bigquery.Client()

# Use format "your-project.your_dataset.your_table_name" for table_id
table_id = your_fully_qualified_table_id
schema = [
    bigquery.SchemaField("name", "STRING"),
    bigquery.SchemaField("post_abbr", "STRING"),
    bigquery.SchemaField("date", "DATE"),
]
table = bigquery.Table(table_id, schema=schema)
table.time_partitioning = bigquery.TimePartitioning(
    type_=bigquery.TimePartitioningType.DAY,
    field="date",  # name of column to use for partitioning
    expiration_ms=1000 * 60 * 60 * 24 * 90,
)  # 90 days

table = client.create_table(table)

print(
    f"Created table {table.project}.{table.dataset_id}.{table.table_id}, "
    f"partitioned on column {table.time_partitioning.field}."
)

Crea una tabla particionada por tiempo de transferencia

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

Console

  1. Abre la página BigQuery en la consola de Google Cloud.

    Ir a la página de BigQuery

  2. En el panel Explorador, expande tu proyecto y selecciona un conjunto de datos.

  3. Expande la opción Acciones y haz clic en Abrir.

  4. En el panel de detalles, haz clic en Crear tabla  (Create table).

  5. En la página Crear tabla, en la sección Origen, selecciona Tabla vacía.

  6. En la sección Destino sigue estos pasos:

    • 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.
    • Verifica que Tipo de tabla esté establecido en Tabla nativa.
  7. En la sección Esquema, ingresa la definición del esquema.

  8. En la sección Configuración de partición y agrupamiento en clústeres, para Partición, haz clic en Partición por tiempo de transferencia.

  9. A fin de solicitar un filtro de partición en todas las consultas de esta tabla, selecciona la casilla de verificación Exigir filtro de partición (opcional). Exigir un filtro de partición puede reducir los costos y mejorar el rendimiento. Si deseas obtener más información, consulta Configura requisitos para filtros de partición.

  10. Haz clic en Crear tabla.

SQL

Para crear una tabla particionada por tiempo de transferencia, usa la declaración CREATE TABLE con una cláusula PARTITION BY que se particiona en_PARTITIONDATE.

En el siguiente ejemplo, se crea una tabla con particiones por día:

  1. En la consola de Google Cloud, ve a la página de BigQuery.

    Ir a BigQuery

  2. En el editor de consultas, ingresa la siguiente sentencia:

    CREATE TABLE
      mydataset.newtable (transaction_id INT64)
    PARTITION BY
      _PARTITIONDATE
      OPTIONS (
        partition_expiration_days = 3,
        require_partition_filter = TRUE);
    

    Usa la cláusula OPTIONS para configurar opciones de tabla como el vencimiento de la partición y los requisitos del filtro de partición.

  3. Haz clic en Ejecutar.

Si deseas obtener información sobre cómo ejecutar consultas, visita Ejecuta una consulta interactiva.

El tipo de partición predeterminado para la partición por tiempo de transferencia es la partición por día. Si deseas especificar un tipo de partición diferente, incluye la función DATE_TRUNC en la cláusula PARTITION BY. Por ejemplo, con la siguiente consulta, se crea una tabla con particiones por mes:

CREATE TABLE
  mydataset.newtable (transaction_id INT64)
PARTITION BY
  DATE_TRUNC(_PARTITIONTIME, MONTH)
  OPTIONS (
    partition_expiration_days = 3,
    require_partition_filter = TRUE);

bq

  1. En la consola de Google Cloud, activa Cloud Shell.

    Activar Cloud Shell

    En la parte inferior de la consola de Google Cloud, se inicia una sesión de Cloud Shell en la que se muestra una ventana de línea de comandos. Cloud Shell es un entorno de shell con Google Cloud CLI ya instalada y con valores ya establecidos para el proyecto actual. La sesión puede tardar unos segundos en inicializarse.

  2. Usa el comando bq mk con la marca --table (o la combinación de teclas -t):

    bq mk \
       --table \
       --schema SCHEMA \
       --time_partitioning_type UNIT_TIME \
       --time_partitioning_expiration EXPIRATION_TIME \
       --require_partition_filter=BOOLEAN  \
       PROJECT_ID:DATASET.TABLE
    

    Reemplaza lo siguiente:

    • SCHEMA: una definición en el formato column:data_type,column:data_type o la ruta a un archivo de esquema JSON en tu máquina local. Si deseas obtener más información, consulta Especifica un esquema.
    • UNIT_TIME: el tipo de partición. Entre los valores admitidos, se encuentran los siguientes DAY, HOUR, MONTH o YEAR.
    • EXPIRATION_TIME: el tiempo de vencimiento de las particiones de la tabla, en segundos. La marca --time_partitioning_expiration es opcional. Para obtener más información, consulta Configura el vencimiento de la partición.
    • BOOLEAN: Si es true, entonces las consultas de esta tabla deben incluir un filtro de partición. La marca --require_partition_filter es opcional. Si deseas obtener más información, consulta Configura requisitos para filtros de partición.
    • PROJECT_ID: El ID del proyecto Si se omite, se usa tu proyecto predeterminado.
    • DATASET: el nombre de un conjunto de datos en tu proyecto.
    • TABLE es el nombre de la tabla que se creará.

    Para obtener más opciones de línea de comandos, consulta bq mk.

    En el siguiente ejemplo, se crea una tabla particionada por tiempo de transferencia llamada mytable. La tabla tiene partición por día, con un vencimiento de partición de 259,200 segundos (3 días).

    bq mk \
       -t \
       --schema qtr:STRING,sales:FLOAT,year:STRING \
       --time_partitioning_type DAY \
       --time_partitioning_expiration 259200 \
       mydataset.mytable
    

Terraform

Usa el recurso google_bigquery_table.

En el siguiente ejemplo, se crea una tabla llamada mytable que se particiona por tiempo de transferencia:

resource "google_bigquery_dataset" "default" {
  dataset_id                      = "mydataset"
  default_partition_expiration_ms = 2592000000  # 30 days
  default_table_expiration_ms     = 31536000000 # 365 days
  description                     = "dataset description"
  location                        = "US"
  max_time_travel_hours           = 96 # 4 days

  labels = {
    billing_group = "accounting",
    pii           = "sensitive"
  }
}

resource "google_bigquery_table" "default" {
  dataset_id          = google_bigquery_dataset.default.dataset_id
  table_id            = "mytable"
  deletion_protection = false # set to "true" in production

  time_partitioning {
    type          = "MONTH"
    expiration_ms = 604800000 # 7 days
  }
  require_partition_filter = true

  schema = <<EOF
[
  {
    "name": "ID",
    "type": "INT64",
    "mode": "NULLABLE",
    "description": "Item ID"
  },
  {
    "name": "Item",
    "type": "STRING",
    "mode": "NULLABLE"
  }
]
EOF

}

Para aplicar tu configuración de Terraform en un proyecto de Google Cloud, completa los pasos de las siguientes secciones.

Prepara Cloud Shell

  1. Inicia Cloud Shell
  2. Establece el proyecto de Google Cloud predeterminado en el que deseas aplicar tus configuraciones de Terraform.

    Solo necesitas ejecutar este comando una vez por proyecto y puedes ejecutarlo en cualquier directorio.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Las variables de entorno se anulan si configuras valores explícitos en el archivo de configuración de Terraform.

Prepara el directorio

Cada archivo de configuración de Terraform debe tener su propio directorio (también llamado módulo raíz).

  1. En Cloud Shell, crea un directorio y un archivo nuevo dentro de ese directorio. El nombre del archivo debe tener la extensión .tf, por ejemplo, main.tf. En este instructivo, el archivo se denomina main.tf.
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf
  2. Si sigues un instructivo, puedes copiar el código de muestra en cada sección o paso.

    Copia el código de muestra en el main.tf recién creado.

    De manera opcional, copia el código de GitHub. Esto se recomienda cuando el fragmento de Terraform es parte de una solución de extremo a extremo.

  3. Revisa y modifica los parámetros de muestra que se aplicarán a tu entorno.
  4. Guarda los cambios.
  5. Inicialice Terraform. Solo debes hacerlo una vez por directorio.
    terraform init

    De manera opcional, incluye la opción -upgrade para usar la última versión del proveedor de Google:

    terraform init -upgrade

Aplica los cambios

  1. Revisa la configuración y verifica que los recursos que creará o actualizará Terraform coincidan con tus expectativas:
    terraform plan

    Corrige la configuración según sea necesario.

  2. Para aplicar la configuración de Terraform, ejecuta el siguiente comando y, luego, escribe yes cuando se te solicite:
    terraform apply

    Espera hasta que Terraform muestre el mensaje “¡Aplicación completa!”.

  3. Abre tu proyecto de Google Cloud para ver los resultados. En la consola de Google Cloud, navega a tus recursos en la IU para asegurarte de que Terraform los haya creado o actualizado.

API

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

Crear una tabla particionada de rango de número entero

Para crear una tabla particionada por rangos de números enteros vacía con una definición de esquema, haz lo siguiente:

Console

  1. Abre la página BigQuery en la consola de Google Cloud.

    Ir a la página de BigQuery

  2. En el panel Explorador, expande tu proyecto y selecciona un conjunto de datos.

  3. Expande la opción Acciones y haz clic en Abrir.

  4. En el panel de detalles, haz clic en Crear tabla  (Create table).

  5. En la página Crear tabla, en la sección Origen, selecciona Tabla vacía.

  6. En la sección Destino sigue estos pasos:

    • 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.
    • Verifica que Tipo de tabla esté establecido en Tabla nativa.
  7. En la sección Esquema, ingresa la definición del esquema. Asegúrate de que el esquema incluya una columna INTEGER para la columna de partición. Si deseas obtener más información, consulta Especifica un esquema.

  8. En la sección Configuración de particiones y clústeres, en la lista desplegable Partición, selecciona Particionar por campo y elige la columna de partición. Esta opción solo está disponible si el esquema contiene una columna INTEGER.

  9. Proporciona valores de inicio, de fin y de intervalo:

    • Inicio es el inicio del primer rango de partición (inclusivo).
    • Fin es el final del último rango de partición (exclusivo).
    • Intervalo es el ancho de cada rango de partición.

    Los valores fuera de estos rangos van a una partición __UNPARTITIONED__ especial.

  10. A fin de solicitar un filtro de partición en todas las consultas de esta tabla, selecciona la casilla de verificación Exigir filtro de partición (opcional). Exigir un filtro de partición puede reducir los costos y mejorar el rendimiento. Si deseas obtener más información, consulta Configura requisitos para filtros de partición.

  11. Haz clic en Crear tabla.

SQL

Para crear una tabla particionada por rangos de números enteros, usa la declaración DDL CREATE TABLE con una cláusula PARTITION BY.

En el siguiente ejemplo, se crea una tabla que se particiona en la columna customer_id con un inicio 0, un fin 100 y un intervalo 10:

  1. En la consola de Google Cloud, ve a la página de BigQuery.

    Ir a BigQuery

  2. En el editor de consultas, ingresa la siguiente sentencia:

    CREATE TABLE mydataset.newtable (customer_id INT64, date1 DATE)
    PARTITION BY
      RANGE_BUCKET(customer_id, GENERATE_ARRAY(0, 100, 10))
      OPTIONS (
        require_partition_filter = TRUE);
    

    Usa la cláusula OPTIONS para configurar las opciones de la tabla, como los requisitos de filtro de partición.

  3. Haz clic en Ejecutar.

Si deseas obtener información sobre cómo ejecutar consultas, visita Ejecuta una consulta interactiva.

bq

  1. En la consola de Google Cloud, activa Cloud Shell.

    Activar Cloud Shell

    En la parte inferior de la consola de Google Cloud, se inicia una sesión de Cloud Shell en la que se muestra una ventana de línea de comandos. Cloud Shell es un entorno de shell con Google Cloud CLI ya instalada y con valores ya establecidos para el proyecto actual. La sesión puede tardar unos segundos en inicializarse.

  2. Usa el comando bq mk con la marca --table (o la combinación de teclas -t):

    bq mk \
       --schema schema \
       --range_partitioning=COLUMN_NAME,START,END,INTERVAL \
       --require_partition_filter=BOOLEAN  \
       PROJECT_ID:DATASET.TABLE
    

    Reemplaza lo siguiente:

    • SCHEMA: una definición de esquema intercalado en el formato column:data_type,column:data_type o la ruta de acceso al archivo de esquema JSON en tu máquina local. Si deseas obtener más información, consulta Especifica un esquema.
    • COLUMN_NAME: el nombre de la columna de partición. En el esquema de la tabla, esta columna debe ser de tipo INTEGER.
    • START: Es el inicio del primer rango de partición (inclusivo).
    • END: el final del último rango de partición (exclusivo).
    • INTERVAL: el ancho de cada rango de partición.
    • BOOLEAN: Si es true, entonces las consultas de esta tabla deben incluir un filtro de partición. La marca --require_partition_filter es opcional. Si deseas obtener más información, consulta Configura requisitos para filtros de partición.
    • PROJECT_ID: El ID del proyecto Si se omite, se usa tu proyecto predeterminado.
    • DATASET: el nombre de un conjunto de datos en tu proyecto.
    • TABLE es el nombre de la tabla que se creará.

    Los valores fuera del rango de partición se envían a una partición __UNPARTITIONED__ especial.

    Para obtener más opciones de línea de comandos, consulta bq mk.

    En el siguiente ejemplo, se crea una tabla llamada mytable que se particiona en la columna customer_id.

    bq mk \
       -t \
       --schema 'customer_id:INTEGER,qtr:STRING,sales:FLOAT' \
       --range_partitioning=customer_id,0,100,10 \
       mydataset.mytable
    

Terraform

Usa el recurso google_bigquery_table.

En el siguiente ejemplo, se crea una tabla llamada mytable particionada por rango de números enteros:

resource "google_bigquery_dataset" "default" {
  dataset_id                      = "mydataset"
  default_partition_expiration_ms = 2592000000  # 30 days
  default_table_expiration_ms     = 31536000000 # 365 days
  description                     = "dataset description"
  location                        = "US"
  max_time_travel_hours           = 96 # 4 days

  labels = {
    billing_group = "accounting",
    pii           = "sensitive"
  }
}

resource "google_bigquery_table" "default" {
  dataset_id          = google_bigquery_dataset.default.dataset_id
  table_id            = "mytable"
  deletion_protection = false # set to "true" in production

  range_partitioning {
    field = "ID"
    range {
      start    = 0
      end      = 1000
      interval = 10
    }
  }
  require_partition_filter = true

  schema = <<EOF
[
  {
    "name": "ID",
    "type": "INT64",
    "description": "Item ID"
  },
  {
    "name": "Item",
    "type": "STRING",
    "mode": "NULLABLE"
  }
]
EOF

}

Para aplicar tu configuración de Terraform en un proyecto de Google Cloud, completa los pasos de las siguientes secciones.

Prepara Cloud Shell

  1. Inicia Cloud Shell
  2. Establece el proyecto de Google Cloud predeterminado en el que deseas aplicar tus configuraciones de Terraform.

    Solo necesitas ejecutar este comando una vez por proyecto y puedes ejecutarlo en cualquier directorio.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Las variables de entorno se anulan si configuras valores explícitos en el archivo de configuración de Terraform.

Prepara el directorio

Cada archivo de configuración de Terraform debe tener su propio directorio (también llamado módulo raíz).

  1. En Cloud Shell, crea un directorio y un archivo nuevo dentro de ese directorio. El nombre del archivo debe tener la extensión .tf, por ejemplo, main.tf. En este instructivo, el archivo se denomina main.tf.
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf
  2. Si sigues un instructivo, puedes copiar el código de muestra en cada sección o paso.

    Copia el código de muestra en el main.tf recién creado.

    De manera opcional, copia el código de GitHub. Esto se recomienda cuando el fragmento de Terraform es parte de una solución de extremo a extremo.

  3. Revisa y modifica los parámetros de muestra que se aplicarán a tu entorno.
  4. Guarda los cambios.
  5. Inicialice Terraform. Solo debes hacerlo una vez por directorio.
    terraform init

    De manera opcional, incluye la opción -upgrade para usar la última versión del proveedor de Google:

    terraform init -upgrade

Aplica los cambios

  1. Revisa la configuración y verifica que los recursos que creará o actualizará Terraform coincidan con tus expectativas:
    terraform plan

    Corrige la configuración según sea necesario.

  2. Para aplicar la configuración de Terraform, ejecuta el siguiente comando y, luego, escribe yes cuando se te solicite:
    terraform apply

    Espera hasta que Terraform muestre el mensaje “¡Aplicación completa!”.

  3. Abre tu proyecto de Google Cloud para ver los resultados. En la consola de Google Cloud, navega a tus recursos en la IU para asegurarte de que Terraform los haya creado o actualizado.

API

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

Java

Antes de probar este ejemplo, sigue las instrucciones de configuración para Java incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Java.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.RangePartitioning;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.StandardTableDefinition;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableInfo;

// Sample to create a range partitioned table
public class CreateRangePartitionedTable {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    Schema schema =
        Schema.of(
            Field.of("integerField", StandardSQLTypeName.INT64),
            Field.of("stringField", StandardSQLTypeName.STRING),
            Field.of("booleanField", StandardSQLTypeName.BOOL),
            Field.of("dateField", StandardSQLTypeName.DATE));
    createRangePartitionedTable(datasetName, tableName, schema);
  }

  public static void createRangePartitionedTable(
      String datasetName, String tableName, Schema schema) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);

      // Note: The field must be a top- level, NULLABLE/REQUIRED field.
      // The only supported type is INTEGER/INT64
      RangePartitioning partitioning =
          RangePartitioning.newBuilder()
              .setField("integerField")
              .setRange(
                  RangePartitioning.Range.newBuilder()
                      .setStart(1L)
                      .setInterval(2L)
                      .setEnd(10L)
                      .build())
              .build();

      StandardTableDefinition tableDefinition =
          StandardTableDefinition.newBuilder()
              .setSchema(schema)
              .setRangePartitioning(partitioning)
              .build();
      TableInfo tableInfo = TableInfo.newBuilder(tableId, tableDefinition).build();

      bigquery.create(tableInfo);
      System.out.println("Range partitioned table created successfully");
    } catch (BigQueryException e) {
      System.out.println("Range partitioned table was not created. \n" + e.toString());
    }
  }
}

Node.js

Antes de probar este ejemplo, sigue las instrucciones de configuración para Node.js incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Node.js.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function createTableRangePartitioned() {
  // Creates a new integer range partitioned table named "my_table"
  // in "my_dataset".

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = "my_dataset";
  // const tableId = "my_table";

  const schema = [
    {name: 'fullName', type: 'STRING'},
    {name: 'city', type: 'STRING'},
    {name: 'zipcode', type: 'INTEGER'},
  ];

  // To use integer range partitioning, select a top-level REQUIRED or
  // NULLABLE column with INTEGER / INT64 data type. Values that are
  // outside of the range of the table will go into the UNPARTITIONED
  // partition. Null values will be in the NULL partition.
  const rangePartition = {
    field: 'zipcode',
    range: {
      start: 0,
      end: 100000,
      interval: 10,
    },
  };

  // For all options, see https://cloud.google.com/bigquery/docs/reference/v2/tables#resource
  const options = {
    schema: schema,
    rangePartitioning: rangePartition,
  };

  // Create a new table in the dataset
  const [table] = await bigquery
    .dataset(datasetId)
    .createTable(tableId, options);

  console.log(`Table ${table.id} created with integer range partitioning: `);
  console.log(table.metadata.rangePartitioning);
}

Python

Antes de probar este ejemplo, sigue las instrucciones de configuración para Python incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Python.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name"

schema = [
    bigquery.SchemaField("full_name", "STRING"),
    bigquery.SchemaField("city", "STRING"),
    bigquery.SchemaField("zipcode", "INTEGER"),
]

table = bigquery.Table(table_id, schema=schema)
table.range_partitioning = bigquery.RangePartitioning(
    # To use integer range partitioning, select a top-level REQUIRED /
    # NULLABLE column with INTEGER / INT64 data type.
    field="zipcode",
    range_=bigquery.PartitionRange(start=0, end=100000, interval=10),
)
table = client.create_table(table)  # Make an API request.
print(
    "Created table {}.{}.{}".format(table.project, table.dataset_id, table.table_id)
)

Crea una tabla particionada a partir de un resultado de consulta

Puedes crear una tabla particionada a partir del resultado de una consulta de las siguientes maneras:

  • En SQL, usa una declaración CREATE TABLE ... AS SELECT. Puedes usar este enfoque para crear una tabla particionada por columna de unidad de tiempo o rango de números enteros, pero no por tiempo de transferencia.
  • Usa la herramienta de línea de comandos de bq o la API de BigQuery a fin de establecer una tabla de destino para una consulta. Cuando se ejecuta la consulta, BigQuery escribe los resultados en la tabla de destino. Puedes usar este enfoque para cualquier tipo de partición.
  • Llama al método de la API jobs.insert y especifica la partición en la propiedad timePartitioning o en la propiedad rangePartitioning.

SQL

Usa la declaración CREATE TABLE con una cláusula SELECT AS para la consulta. Incluye una cláusula PARTITION BY para configurar la partición.

En el siguiente ejemplo, se crea una tabla que se particiona en la columna transaction_date:

  1. En la consola de Google Cloud, ve a la página de BigQuery.

    Ir a BigQuery

  2. En el editor de consultas, ingresa la siguiente sentencia:

    CREATE TABLE
      mydataset.newtable (transaction_id INT64, transaction_date DATE)
    PARTITION BY
      transaction_date
    AS (
      SELECT
        transaction_id, transaction_date
      FROM
        mydataset.mytable
    );
    

    Usa la cláusula OPTIONS para configurar las opciones de la tabla, como los requisitos de filtro de partición.

  3. Haz clic en Ejecutar.

Si deseas obtener información sobre cómo ejecutar consultas, visita Ejecuta una consulta interactiva.

bq

  1. En la consola de Google Cloud, activa Cloud Shell.

    Activar Cloud Shell

    En la parte inferior de la consola de Google Cloud, se inicia una sesión de Cloud Shell en la que se muestra una ventana de línea de comandos. Cloud Shell es un entorno de shell con Google Cloud CLI ya instalada y con valores ya establecidos para el proyecto actual. La sesión puede tardar unos segundos en inicializarse.

  2. Para crear una tabla particionada a partir de una consulta, usa el comando bq query con la marca --destination_table y la marca --time_partitioning_type.

    Partición por columnas de unidad de tiempo:

    bq query \
       --use_legacy_sql=false \
       --destination_table TABLE_NAME \
       --time_partitioning_field COLUMN \
       --time_partitioning_type UNIT_TIME \
       'QUERY_STATEMENT'
    

    Partición por tiempo de transferencia:

    bq query \
       --use_legacy_sql=false \
       --destination_table TABLE_NAME \
       --time_partitioning_type UNIT_TIME \
       'QUERY_STATEMENT'
    

    Partición por rangos de números enteros:

    bq query \
       --use_legacy_sql=false \
       --destination_table PROJECT_ID:DATASET.TABLE \
       --range_partitioning COLUMN,START,END,INTERVAL \
       'QUERY_STATEMENT'
    

    Reemplaza lo siguiente:

    • PROJECT_ID: El ID del proyecto Si se omite, se usa tu proyecto predeterminado.
    • DATASET: el nombre de un conjunto de datos en tu proyecto.
    • TABLE es el nombre de la tabla que se creará.
    • COLUMN: el nombre de la columna de partición.
    • UNIT_TIME: el tipo de partición. Entre los valores admitidos, se encuentran los siguientes DAY, HOUR, MONTH o YEAR.
    • START: el inicio de la partición del rango (inclusivo)
    • END: el fin de la partición de rango (exclusivo).
    • INTERVAL es el ancho de cada rango dentro de la partición.
    • QUERY_STATEMENT: la consulta que se usa para propagar la tabla.

    En el siguiente ejemplo, se crea una tabla particionada en la columna transaction_date mediante una partición mensual.

    bq query \
       --use_legacy_sql=false \
       --destination_table mydataset.newtable \
       --time_partitioning_field transaction_date \
       --time_partitioning_type MONTH \
       'SELECT transaction_id, transaction_date FROM mydataset.mytable'
    

    En el siguiente ejemplo, se crea una tabla particionada en la columna customer_id mediante una partición de rangos de números enteros.

    bq query \
       --use_legacy_sql=false \
       --destination_table mydataset.newtable \
       --range_partitioning customer_id,0,100,10 \
       'SELECT * FROM mydataset.ponies'
    

    Para las tablas particionadas por tiempo de transferencia, también puedes cargar datos en una partición específica mediante un decorador de particiones. En el siguiente ejemplo, se crea una nueva tabla particionada por tiempo de transferencia y se cargan datos en la partición 20180201 (1 de febrero de 2018):

    bq query \
       --use_legacy_sql=false  \
       --time_partitioning_type=DAY \
       --destination_table='newtable$20180201' \
       'SELECT * FROM mydataset.mytable'
    

API

Para guardar los resultados de la consulta en una tabla particionada, llama al método jobs.insert. Configura un trabajo query. Especifica la tabla de destino en destinationTable. Especifica la partición en la propiedad timePartitioning o en la propiedad rangePartitioning.

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.

bq --location=LOCATION partition \
    --time_partitioning_type=PARTITION_TYPE \
    --time_partitioning_expiration INTEGER \
    PROJECT_ID:SOURCE_DATASET.SOURCE_TABLE \
    PROJECT_ID:DESTINATION_DATASET.DESTINATION_TABLE

Reemplaza lo siguiente:

  • LOCATION: El nombre de tu ubicación. La marca --location es opcional.
  • PARTITION_TYPE: el tipo de partición. Los valores posibles son DAY, HOUR, MONTH o YEAR.
  • INTEGER: el tiempo de vencimiento de la partición, en segundos. No hay un valor mínimo. El tiempo 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. La marca time_partitioning_expiration es opcional.
  • PROJECT_ID: ID del proyecto
  • SOURCE_DATASET: el conjunto de datos que contiene las tablas fragmentadas por fecha.
  • SOURCE_TABLE: el prefijo de tus tablas fragmentadas por fecha.
  • DESTINATION_DATASET: El conjunto de datos para la tabla particionada nueva.
  • DESTINATION_TABLE: El nombre de la tabla particionada que se creará.

El comando partition no admite las marcas --label, --expiration, --add_tags o --description. Puedes agregar etiquetas, un vencimiento de tabla, etiquetas de instancia y una descripción para la tabla luego de su creación.

Cuando ejecutas el comando partition, BigQuery crea un trabajo de copia que genera particiones de tablas fragmentadas.

En el siguiente ejemplo, se crea una tabla particionada por tiempo de transferencia llamada mytable_partitioned a partir de un conjunto de tablas fragmentadas por fecha con el prefijo sourcetable_. La tabla nueva se particiona por día, con un vencimiento de partición de 259,200 segundos (3 días).

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

Si las tablas fragmentadas por fecha fueran sourcetable_20180126 y sourcetable_20180127, este comando crearía las siguientes particiones: mydataset.mytable_partitioned$20180126 y mydataset.mytable_partitioned$20180127.

Seguridad de la tabla particionada

El control de acceso para las tablas particionadas es el mismo que el de las tablas estándar. Para obtener más información, consulta Introducción a los controles de acceso a tablas.

¿Qué sigue?