Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

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:

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:

  • Hasta 1,024 caracteres
  • 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:

  • 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....datasest_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 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 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

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

  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, selecciona 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, selecciona el conjunto de datos en el que deseas crear la tabla.
      2. En el campo Tabla, ingresa 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. 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. Para Orden de agrupamiento en clústeres, ingresa entre uno y cuatro nombres de columna separados por comas.
    5. 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.
    6. Haga 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.

  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.myclusteredtable
    (
      customer_id STRING,
      transaction_amount NUMERIC
    )
    CLUSTER BY
      customer_id
      OPTIONS (
        description = 'a table clustered by customer_id');
    

  3. Haz clic en Ejecutar.

Si quieres obtener información para ejecutar consultas, visita Ejecuta consultas interactivas.

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: es 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.

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.

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.

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.

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:

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:

  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.clustered_table
    (
      customer_id STRING,
      transaction_amount NUMERIC
    )
    CLUSTER BY
      customer_id
    AS (
      SELECT * FROM mydataset.unclustered_table
    );
    

  3. Haz clic en Ejecutar.

Si quieres obtener información para ejecutar consultas, visita Ejecuta consultas interactivas.

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 SQL estándar de Google. 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.

  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:

    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']);
    

  3. Haz clic en Ejecutar.

Si quieres obtener información para ejecutar consultas, visita Ejecuta consultas interactivas.

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

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.

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

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.

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

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.

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

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 de la herramienta de línea de comandos bq show
  • 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

  1. En Google Cloud Console, 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.

  2. Haz clic en Detalles. En esta página, se muestran los detalles de la tabla que incluyen las columnas de agrupamiento en clústeres.

    Detalles de la tabla.

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:

  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.data (column1 INT64, column2 INT64)
    CLUSTER BY column1, column2;
    SELECT
      column_name, clustering_ordinal_position
    FROM
      mydataset.INFORMATION_SCHEMA.COLUMNS;
    

  3. Haz clic en Ejecutar.

Si quieres obtener información para ejecutar consultas, visita Ejecuta consultas interactivas.

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.
  • Usa el comando bq de la herramienta de línea de comandos bq ls
  • 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.

Puedes cambiar la especificación del agrupamiento en clústeres de las siguientes maneras:

  • Realiza una llamada al método de API tables.update o tables.patch.

  • Llama al comando bq update de la herramienta de línea de comandos de bq con la marca --clustering_fields.

Cuando se convierte una tabla que no está agrupada en clústeres a una agrupada, o se cambia el conjunto de columnas agrupadas, el reagrupamiento en clústeres automático solo funciona a partir de ese momento. Por ejemplo, una tabla de 1 PB no agrupada que se convierte en una tabla agrupada mediante tables.update seguirá teniendo 1 PB de datos no agrupados. El reagrupamiento en clústeres automático solo se aplica a los datos nuevos que se agregan a la tabla después de la actualización.

Seguridad de las tablas

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

Próximos pasos