Crea y usa tablas agrupadas

En este documento se describe el proceso para crear y usar tablas agrupadas en BigQuery. Para obtener una descripción general de la compatibilidad con tablas agrupadas en BigQuery, consulta Introducción a las tablas agrupadas.

Crea tablas agrupadas en clústeres

Puedes crear una tabla agrupada en clústeres con los siguientes métodos:

Crea una tabla a partir de un resultado de consulta:
- Ejecuta una sentencia CREATE TABLE AS SELECT de DDL.
- Ejecuta una consulta que cree una tabla de destino agrupada en clústeres.
Usa una sentencia CREATE TABLE de DDL con una cláusula CLUSTER BY que contenga una clustering_column_list.
Ejecuta el comando bq mk de la herramienta de línea de comandos de bq.
Realiza llamadas al método de la API de tables.insert.
Carga datos en BigQuery.
Usa las bibliotecas cliente.

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 puede contener lo siguiente:

Contiene caracteres con un total de hasta 1,024 bytes UTF-8.
Caracteres Unicode en la categoría L (letra), M (marca), N (número), Pc (conector, incluido el guion bajo), Pd (raya) y Zs (espacio) Para obtener más información, consulta la Categoría general.

A continuación, se muestran todos los ejemplos de nombres de tabla válidos: table 01, ग्राहक, 00_お客様y étudiant-01.

Advertencias:

Los nombres de tablas distinguen entre mayúsculas y minúsculas de forma predeterminada. mytable y MyTable pueden coexistir en el mismo conjunto de datos, a menos que sean parte de un conjunto de datos con la distinción entre mayúsculas y minúsculas desactivada.
Algunos nombres de tablas y prefijos de nombres de tablas están reservados. Si recibes un error que indica que el nombre o prefijo de la tabla está reservado, selecciona un nombre diferente y vuelve a intentarlo.
Si incluyes múltiples operadores de punto (.) en una secuencia, los operadores duplicados se quitan de forma implícita.

Por ejemplo, esto: project_name....dataset_name..table_name

Se convierte en esto: project_name.dataset_name.table_name

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 uno de los siguientes roles predefinidos 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 agrupada en clústeres vacía con una definición de esquema

Cuando creas una tabla en BigQuery, especificas las columnas de agrupamiento en clústeres. Después de crear la tabla, puedes modificar las columnas de clústeres. Consulta Modifica la especificación de agrupamiento en clústeres para obtener más información.

Las columnas de agrupamiento en clústeres deben ser de nivel superior, no se deben repetir y deben ser de uno de los tipos de datos simples siguientes:

DATE
BOOLEAN
GEOGRAPHY
INTEGER
NUMERIC
BIGNUMERIC
STRING
TIMESTAMP
RANGE (vista previa)

Puedes especificar hasta cuatro columnas de agrupamiento en clústeres. Cuando especificas varias columnas, el orden de las columnas determina el orden de los datos. Por ejemplo, si la tabla está agrupada en las columnas a, b y c, los datos se ordenan en el mismo orden: primero por la columna a, luego por la b y, por último, por la columna c. Como práctica recomendada, coloca en primer lugar a la columna que se filtra o se agrega con mayor frecuencia.

El orden de las columnas de agrupamiento en clústeres también afecta el rendimiento y el precio de la consulta. Si deseas obtener más información sobre las prácticas recomendadas de consulta para tablas agrupadas, ve a la sección Consulta tablas agrupadas.

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

Console

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

Ir a BigQuery
En el panel Explorador, expande tu proyecto y, luego, elige un conjunto de datos.
En la sección Información del conjunto de datos, haz clic en Crear tabla.
En el panel Crear tabla, especifica los siguientes detalles:

En la sección Fuente, selecciona Tabla vacía en la lista Crear tabla desde.
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.
En la sección Esquema, ingresa la definición del 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.
Para Orden de agrupamiento en clústeres, ingresa entre uno y cuatro nombres de columna separados por comas.
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 del cliente almacenado en reposo mediante una clave de Google y administrada por Google.
Haz clic en Crear tabla.

SQL

Usa el comando CREATE TABLE DDL statement con la opción CLUSTER BY. En el siguiente ejemplo, se crea una tabla agrupada en clústeres llamada myclusteredtable en mydataset.

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

Ir a BigQuery

En el editor de consultas, escribe la siguiente sentencia:

CREATE TABLE mydataset.myclusteredtable
(
  customer_id STRING,
  transaction_amount NUMERIC
)
CLUSTER BY
  customer_id
  OPTIONS (
    description = 'a table clustered by customer_id');

Haz clic en Ejecutar.

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

bq

Usa el comando bq mk con las siguientes marcas:

--table (o la combinación de teclas -t)
--schema. Puedes proporcionar la definición del esquema de la tabla de forma intercalada o usar un archivo de esquema JSON
--clustering_fields. Puedes especificar hasta cuatro columnas de agrupamiento en clústeres

Los parámetros opcionales incluyen --expiration, --description, --time_partitioning_type, --time_partitioning_field, --time_partitioning_expiration, --destination_kms_key y --label.

Si creas una tabla en otro proyecto que no sea el predeterminado, agrega el ID del proyecto al conjunto de datos en el formato siguiente: project_id:dataset.

--destination_kms_key no se muestra aquí. Para obtener más información sobre el uso de --destination_kms_key, consulta las claves de encriptación administradas por el cliente.

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

bq mk \
    --table \
    --expiration INTEGER1 \
    --schema SCHEMA \
    --clustering_fields CLUSTER_COLUMNS \
    --description "DESCRIPTION" \
    --label KEY:VALUE,KEY:VALUE \
    PROJECT_ID:DATASET.TABLE

Reemplaza lo siguiente:

INTEGER1: La duración predeterminada, en segundos, de la tabla. El valor mínimo es 3,600 segundos (una hora). La hora de vencimiento se evalúa según la hora UTC actual más el valor de número entero. Si configuras la fecha de vencimiento de la tabla cuando creas una tabla, se ignora la configuración predeterminada del vencimiento de la tabla para el conjunto de datos. Si configuras este valor, la tabla se borra después de la hora especificada.
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.
CLUSTER_COLUMNS: Una lista separada por comas de hasta cuatro columnas de agrupamiento en clústeres. La lista no puede contener espacios.
DESCRIPTION: Una descripción de la tabla, entre comillas.
KEY:VALUE: El par clave-valor que representa una etiqueta. Puedes ingresar varias etiquetas mediante una lista separada por comas.
PROJECT_ID: El ID de tu proyecto.
DATASET: Un conjunto de datos en tu proyecto.
TABLE: es el nombre de la tabla que crearás.

Cuando especificas el esquema en la línea de comandos, no puedes incluir un tipo 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 RECORD, proporciona un archivo de esquema JSON en su lugar.

Ejemplos:

Ingresa el siguiente comando para crear una tabla particionada llamada myclusteredtable en mydataset en tu proyecto predeterminado. 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 clustered table y la etiqueta en organization:development. El comando usa el acceso directo -t en lugar de --table.

El esquema está especificado de forma intercalada como: timestamp:timestamp,customer_id:string,transaction_amount:float. El campo de agrupamiento en clústeres especificado customer_id se usa para agrupar en clústeres la tabla.

bq mk \
    -t \
    --expiration 2592000 \
    --schema 'timestamp:timestamp,customer_id:string,transaction_amount:float' \
    --clustering_fields customer_id \
    --description "This is my clustered table" \
    --label org:dev \
    mydataset.myclusteredtable

Ingresa el siguiente comando para crear una tabla agrupada llamada myclusteredtable en myotherproject, no en tu proyecto predeterminado. La descripción se establece como This is my clustered table y la etiqueta como 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 el conjunto de datos no tiene un vencimiento de tabla predeterminado, la tabla no se vencerá nunca.

El esquema se especifica en un archivo JSON local: /tmp/myschema.json. El campo customer_id se usa para agrupar en clústeres la tabla.

bq mk \
    -t \
    --expiration 2592000 \
    --schema /tmp/myschema.json \
    --clustering_fields=customer_id \
    --description "This is my clustered table" \
    --label org:dev \
    myotherproject:mydataset.myclusteredtable

Una vez que se crea la tabla, puedes actualizar la descripción y las etiquetas de la tabla.

Terraform

Usa el recurso google_bigquery_table.

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.

En el siguiente ejemplo, se crea una tabla llamada mytable agrupada en clústeres en las columnas ID y Created:

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

  clustering = ["ID", "Created"]

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

}

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

Prepara Cloud Shell

Inicia Cloud Shell
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).

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
```
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.
Revisa y modifica los parámetros de muestra que se aplicarán a tu entorno.
Guarda los cambios.
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
```

Aplique los cambios

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.
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 “Apply complete!”.
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 clustering.fields y schema.

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.clustering_fields = ["city", "zipcode"]
table = client.create_table(table)  # Make an API request.
print(
    "Created clustered table {}.{}.{}".format(
        table.project, table.dataset_id, table.table_id
    )
)

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"
)

// createTableClustered demonstrates creating a BigQuery table with advanced properties like
// partitioning and clustering features.
func createTableClustered(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: "timestamp", Type: bigquery.TimestampFieldType},
		{Name: "origin", Type: bigquery.StringFieldType},
		{Name: "destination", Type: bigquery.StringFieldType},
		{Name: "amount", Type: bigquery.NumericFieldType},
	}
	metaData := &bigquery.TableMetadata{
		Schema: sampleSchema,
		TimePartitioning: &bigquery.TimePartitioning{
			Field:      "timestamp",
			Expiration: 90 * 24 * time.Hour,
		},
		Clustering: &bigquery.Clustering{
			Fields: []string{"origin", "destination"},
		},
	}
	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.Clustering;
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;
import com.google.common.collect.ImmutableList;

public class CreateClusteredTable {
  public static void runCreateClusteredTable() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    createClusteredTable(datasetName, tableName);
  }

  public static void createClusteredTable(String datasetName, String tableName) {
    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.of(TimePartitioning.Type.DAY);

      Schema schema =
          Schema.of(
              Field.of("name", StandardSQLTypeName.STRING),
              Field.of("post_abbr", StandardSQLTypeName.STRING),
              Field.of("date", StandardSQLTypeName.DATE));

      Clustering clustering =
          Clustering.newBuilder().setFields(ImmutableList.of("name", "post_abbr")).build();

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

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

Crea una tabla agrupada en clústeres a partir del resultado de una consulta

Existen dos maneras de crear una tabla agrupada a partir del resultado de una consulta:

Escribe los resultados en una tabla de destino nueva y especifica las columnas de agrupamiento en clústeres.
Con una declaración DDL CREATE TABLE AS SELECT. Para obtener más información sobre este método, consulta Crea una tabla agrupada a partir del resultado de una consulta en la página Usa declaraciones del lenguaje de definición de datos.

Puedes crear una tabla agrupada si realizas consultas en una tabla particionada o en una tabla sin particiones. No puedes cambiar una tabla existente a una tabla agrupada con los resultados de una consulta.

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

SQL

Para crear una tabla agrupada en clústeres a partir de un resultado de consulta, usa la sentencia DDL CREATE TABLE con la opción CLUSTER BY. En el siguiente ejemplo, se crea una tabla nueva agrupada en clústeres según customer_id mediante una consulta a una tabla no agrupada existente:

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

Ir a BigQuery

En el editor de consultas, escribe la siguiente sentencia:

CREATE TABLE mydataset.clustered_table
(
  customer_id STRING,
  transaction_amount NUMERIC
)
CLUSTER BY
  customer_id
AS (
  SELECT * FROM mydataset.unclustered_table
);

Haz clic en Ejecutar.

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

bq

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

bq --location=LOCATION query \
    --use_legacy_sql=false 'QUERY'

Reemplaza lo siguiente:

LOCATION: El nombre de tu ubicación. La marca --location es opcional. Por ejemplo, si usas BigQuery en la región de Tokio, puedes establecer el valor de la marca en asia-northeast1. Puedes configurar un valor predeterminado para la ubicación con el archivo .bigqueryrc.
QUERY: Una consulta en la sintaxis de GoogleSQL. Por el momento, no puedes usar SQL heredado para realizar consultas en las tablas agrupadas o escribir resultados de consultas en tablas agrupadas. La consulta puede contener una declaración DDL CREATE TABLE que especifica las opciones para crear tu tabla agrupada. Puedes usar DDL en vez de especificar las marcas de línea de comandos individuales.

Ejemplos:

Ingresa el siguiente comando para escribir los resultados de la consulta en una tabla de destino agrupada llamada myclusteredtable en mydataset. mydataset está en tu proyecto predeterminado. La consulta recupera datos de una tabla sin particiones: mytable. La columna customer_id de la tabla se usa para agrupar en clústeres la tabla. La columna timestamp de la tabla se usa para crear una tabla particionada.

bq query --use_legacy_sql=false \
    'CREATE TABLE
       mydataset.myclusteredtable
     PARTITION BY
       DATE(timestamp)
     CLUSTER BY
       customer_id
     AS (
       SELECT
         *
       FROM
         `mydataset.mytable`
     );'

API

Para guardar los resultados de la consulta en una tabla agrupada, llama al método jobs.insert, configura un trabajo query y, además, incluye una declaración DDL CREATE TABLE que crea la tabla agrupada.

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

Crea una tabla agrupada en clústeres cuando cargas datos

Puedes crear una tabla agrupada si especificas columnas de agrupamiento en clústeres cuando cargas datos en una tabla nueva. No es necesario crear una tabla vacía antes de cargarle datos. Puedes crear una tabla agrupada y cargar tus datos al mismo tiempo.

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

Para definir el agrupamiento en clústeres cuando defines un trabajo de carga, haz lo siguiente:

SQL

Usa la sentencia LOAD DATA: En el siguiente ejemplo, se cargan datos de AVRO para crear una tabla particionada según el campo transaction_date y agrupada por el campo customer_id. También configura las particiones para que caduquen después de tres días.

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

Ir a BigQuery

En el editor de consultas, escribe la siguiente sentencia:

LOAD DATA INTO mydataset.mytable
PARTITION BY transaction_date
CLUSTER BY customer_id
  OPTIONS (
    partition_expiration_days = 3)
FROM FILES(
  format = 'AVRO',
  uris = ['gs://bucket/path/file.avro']);

Haz clic en Ejecutar.

Para obtener más información sobre cómo ejecutar consultas, visita Ejecuta una consulta interactiva.

API

Para definir la configuración del agrupamiento en clústeres cuando creas una tabla a través de un trabajo de carga, puedes propagar las propiedades Clustering de la tabla.

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"

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

// importClusteredTable demonstrates creating a table from a load job and defining partitioning and clustering
// properties.
func importClusteredTable(projectID, destDatasetID, destTableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/sample-transactions/transactions.csv")
	gcsRef.SkipLeadingRows = 1
	gcsRef.Schema = bigquery.Schema{
		{Name: "timestamp", Type: bigquery.TimestampFieldType},
		{Name: "origin", Type: bigquery.StringFieldType},
		{Name: "destination", Type: bigquery.StringFieldType},
		{Name: "amount", Type: bigquery.NumericFieldType},
	}
	loader := client.Dataset(destDatasetID).Table(destTableID).LoaderFrom(gcsRef)
	loader.TimePartitioning = &bigquery.TimePartitioning{
		Field: "timestamp",
	}
	loader.Clustering = &bigquery.Clustering{
		Fields: []string{"origin", "destination"},
	}
	loader.WriteDisposition = bigquery.WriteEmpty

	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}

	if status.Err() != nil {
		return fmt.Errorf("job completed with error: %v", status.Err())
	}
	return nil
}

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.Clustering;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TimePartitioning;
import com.google.common.collect.ImmutableList;

public class LoadTableClustered {

  public static void runLoadTableClustered() throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "/path/to/file.csv";
    loadTableClustered(datasetName, tableName, sourceUri);
  }

  public static void loadTableClustered(String datasetName, String tableName, String sourceUri)
      throws Exception {
    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);

      Schema schema =
          Schema.of(
              Field.of("name", StandardSQLTypeName.STRING),
              Field.of("post_abbr", StandardSQLTypeName.STRING),
              Field.of("date", StandardSQLTypeName.DATE));

      TimePartitioning partitioning = TimePartitioning.of(TimePartitioning.Type.DAY);

      Clustering clustering =
          Clustering.newBuilder().setFields(ImmutableList.of("name", "post_abbr")).build();

      LoadJobConfiguration loadJobConfig =
          LoadJobConfiguration.builder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.csv())
              .setSchema(schema)
              .setTimePartitioning(partitioning)
              .setClustering(clustering)
              .build();

      Job loadJob = bigquery.create(JobInfo.newBuilder(loadJobConfig).build());

      // Load data from a GCS parquet file into the table
      // Blocks until this load table job completes its execution, either failing or succeeding.
      Job completedJob = loadJob.waitFor();

      // Check for errors
      if (completedJob == null) {
        throw new Exception("Job not executed since it no longer exists.");
      } else if (completedJob.getStatus().getError() != null) {
        // You can also look at queryJob.getStatus().getExecutionErrors() for all
        // errors, not just the latest one.
        throw new Exception(
            "BigQuery was unable to load into the table due to an error: \n"
                + loadJob.getStatus().getError());
      }
      System.out.println("Data successfully loaded into clustered table during load job");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Data not loaded into clustered table during load job \n" + e.toString());
    }
  }
}

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"

job_config = bigquery.LoadJobConfig(
    skip_leading_rows=1,
    source_format=bigquery.SourceFormat.CSV,
    schema=[
        bigquery.SchemaField("timestamp", bigquery.SqlTypeNames.TIMESTAMP),
        bigquery.SchemaField("origin", bigquery.SqlTypeNames.STRING),
        bigquery.SchemaField("destination", bigquery.SqlTypeNames.STRING),
        bigquery.SchemaField("amount", bigquery.SqlTypeNames.NUMERIC),
    ],
    time_partitioning=bigquery.TimePartitioning(field="timestamp"),
    clustering_fields=["origin", "destination"],
)

job = client.load_table_from_uri(
    ["gs://cloud-samples-data/bigquery/sample-transactions/transactions.csv"],
    table_id,
    job_config=job_config,
)

job.result()  # Waits for the job to complete.

table = client.get_table(table_id)  # Make an API request.
print(
    "Loaded {} rows and {} columns to {}".format(
        table.num_rows, len(table.schema), table_id
    )
)

Controla el acceso a las tablas agrupadas en clústeres

Para configurar el acceso a las tablas y vistas, puedes otorgar una función de IAM a una entidad en los siguientes niveles, ordenados según el rango de recursos permitidos (de mayor a menor):

un nivel alto en la jerarquía de recursos de Google Cloud, como el nivel de proyecto, organización o carpeta
el nivel del conjunto de datos
el nivel de la tabla o la vista

También puedes restringir el acceso a los datos dentro de las tablas con los siguientes métodos:

El acceso con cualquier recurso protegido por IAM es aditivo. Por ejemplo, si una entidad no tiene acceso en un nivel alto, como un proyecto, podrías otorgar acceso a la entidad a nivel del conjunto de datos. Luego, la entidad tendrá acceso a las tablas y vistas del conjunto de datos. Del mismo modo, si la entidad no tiene acceso en el nivel alto o en el de conjunto de datos, puedes otorgar acceso a la entidad a nivel de tabla o de vista.

Si otorgas funciones de 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, la entidad tiene acceso a un amplio conjunto de recursos. Por ejemplo, cuando se otorga una función a una entidad en el nivel de proyecto, se le brindan permisos que se aplican a todos los conjuntos de datos del proyecto.

Si 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, incluso si la entidad no tiene acceso a un nivel superior. Para obtener información sobre la configuración de los controles de acceso a nivel de conjunto de datos, consulta Controla el acceso a los conjuntos de datos.

Cuando se otorga una función a nivel de tabla o vista, se especifican las operaciones que una entidad puede realizar en las tablas y vistas específicas, incluso si la entidad no tiene acceso a un nivel superior. Para obtener información sobre la configuración de los controles de acceso a nivel de tabla, consulta Controla el acceso a las tablas y vistas.

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

No puedes establecer un permiso de denegación en ningún recurso protegido por IAM.

Para obtener más información sobre los roles y los permisos, consulta Comprende los roles en la documentación de IAM y los roles y permisos de IAM de BigQuery.

Usa tablas agrupadas en clústeres

Obtén información sobre las tablas agrupadas en clústeres

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

Usa la consola de Google Cloud
Usa el comando bq show de la herramienta de línea de comandos de bq.
Mediante una llamada al método de la API tables.get
Consulta las vistas INFORMATION_SCHEMA.

Permisos necesarios

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

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

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

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

Obtén información sobre tablas agrupadas en clústeres

Para ver información sobre una tabla agrupada, haz lo siguiente:

Console

En la consola de Google Cloud, ve al panel Resources (Recursos). Haz clic en el nombre de tu conjunto de datos para expandirlo y, luego, haz clic en el nombre de la tabla que deseas ver.
Haz clic en Detalles. En esta página, se muestran los detalles de la tabla que incluyen las columnas de agrupamiento en clústeres.

SQL

En cuanto a las tablas agrupadas, puedes consultar la columna CLUSTERING_ORDINAL_POSITION en la vista INFORMATION_SCHEMA.COLUMNS para encontrar el desplazamiento 1 indexado de la columna dentro de las columnas de agrupamiento en clústeres de la tabla:

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

Ir a BigQuery

En el editor de consultas, escribe la siguiente sentencia:

CREATE TABLE mydataset.data (column1 INT64, column2 INT64)
CLUSTER BY column1, column2;
SELECT
  column_name, clustering_ordinal_position
FROM
  mydataset.INFORMATION_SCHEMA.COLUMNS;

Haz clic en Ejecutar.

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

La posición ordinal del agrupamiento en clústeres es 1 para column1 y 2 para column2. Hay más metadatos de tabla disponibles a través de las vistas TABLES, TABLE_OPTIONS, COLUMNS y COLUMN_FIELD_PATH en INFORMATION_SCHEMA.

bq

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

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

bq show \
    --schema \
    --format=prettyjson \
    PROJECT_ID:DATASET.TABLE

Reemplaza lo siguiente:

PROJECT_ID: El ID de tu proyecto.
DATASET: El nombre del conjunto de datos.
TABLE: El nombre de la tabla.

Ejemplos:

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

bq show --format=prettyjson mydataset.myclusteredtable

El resultado debería ser similar a lo siguiente:

{
  "clustering": {
    "fields": [
      "customer_id"
    ]
  },
...
}

API

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

Enumera tablas agrupadas en clústeres en un conjunto de datos

Puedes enumerar las tablas que están agrupadas en clústeres en los conjuntos de datos de las siguientes maneras:

Usa la consola de Google Cloud
Usar el comando bq ls de la herramienta de línea de comandos de bq
Mediante una llamada al método de la API tables.list.
Usa las bibliotecas cliente.
Consulta a la columna CLUSTERING_ORDINAL_POSITION en la vista INFORMATION_SCHEMA.COLUMNS.

Los permisos y los pasos requeridos a fin de crear una lista de tablas agrupadas son los mismos que para las tablas estándar. Si deseas obtener más información sobre cómo enumerar tablas, consulta la sección Enumera las tablas de un conjunto de datos.

Modifica las especificaciones de agrupamiento en clústeres

Puedes cambiar o quitar las especificaciones de agrupamiento en clústeres de una tabla o cambiar el conjunto de columnas agrupadas en una tabla agrupada. Este método de actualización del conjunto de columnas de agrupamiento en clústeres es útil para tablas que usan inserciones de transmisión continua, ya que otros métodos no pueden intercambiar con facilidad esas tablas.

Sigue estos pasos para aplicar una especificación de agrupamiento en clústeres nueva a tablas no particionadas o particionadas.

En la herramienta de bq, actualiza la especificación de agrupamiento en clústeres de tu tabla para que coincida con el agrupamiento en clústeres nuevo:
```
 bq update --clustering_fields=CLUSTER_COLUMN DATASET.ORIGINAL_TABLE 
```
Reemplaza lo siguiente:
- CLUSTER_COLUMN: la columna en la que se agrupa en clústeres, por ejemplo, mycolumn
- DATASET: el nombre del conjunto de datos que contiene la tabla; por ejemplo, mydataset
- ORIGINAL_TABLE: el nombre de tu tabla original; por ejemplo, mytable
También puedes llamar al método tables.update o tables.patch de la API para modificar la especificación del agrupamiento en clústeres.
Para agrupar todas las filas según la especificación de agrupamiento en clústeres nueva, ejecuta la siguiente declaración UPDATE:
```
UPDATE DATASET.ORIGINAL_TABLE SET CLUSTER_COLUMN=CLUSTER_COLUMN WHERE true
```
Nota: Si se aplica una especificación de agrupamiento en clústeres nueva a una tabla que está en almacenamiento a largo plazo, la tabla volverá a los precios de almacenamiento activos. Para obtener más información, consulta los precios de almacenamiento.

Seguridad de las tablas

Para controlar el acceso a las tablas en BigQuery, consulta Introducción a los controles de acceso a tablas.

¿Qué sigue?

Para obtener información sobre cómo consultar tablas agrupadas en clústeres, visita Consulta tablas agrupadas.
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 tablas particionadas, consulta Crea tablas particionadas.
Para ver una descripción general de INFORMATION_SCHEMA, consulta Introducción a INFORMATION_SCHEMA de BigQuery.