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.

Limitaciones

Las tablas agrupadas en BigQuery están sujetas a las limitaciones siguientes:

• Solo se admite SQL estándar para consultar las tablas agrupadas y escribir los resultados de consultas en tablas agrupadas.

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

  • DATE
  • BOOL
  • GEOGRAPHY
  • INT64
  • NUMERIC
  • BIGNUMERIC
  • STRING
  • TIMESTAMP
  • DATETIME

  Para obtener más información sobre los tipos de datos, consulta Tipos de datos de SQL estándar.

• Puedes especificar hasta cuatro columnas de agrupamiento en clústeres.

• Cuando se usan columnas de tipo STRING para el agrupamiento en clústeres, BigQuery usa solo los primeros 1,024 caracteres a fin de agrupar los datos. Los valores de las columnas pueden tener más de 1,024 caracteres.

Crea tablas agrupadas

Puedes crear una tabla agrupada en clústeres de las siguientes maneras:

• A partir de los resultados de una consulta:
  • Con una declaración DDL CREATE TABLE AS SELECT
  • Con la ejecución de una consulta que cree una tabla de destino agrupada
• Mediante una declaración DDL CREATE TABLE con una cláusula CLUSTER BY que contenga una clustering_column_list
• De forma manual, mediante el comando bq mk de la herramienta de línea de comandos de bq.
• De manera programática, con una llamada al método tables.insert de la API
• Cuando cargas datos
• Mediante 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:

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

Por ejemplo, los siguientes son nombres de tabla válidos: table-01, ग्राहक, 00_お客様, étudiant.

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.

Permisos necesarios

Como mínimo, para crear una tabla, debes tener los siguientes permisos:

• Permisos bigquery.tables.create para crear la tabla
• bigquery.tables.updateData para escribir datos en la tabla mediante un trabajo de carga, de consulta o de copia
• bigquery.jobs.create para ejecutar un trabajo de consulta, de carga o de copia que escriba datos en la tabla

Es posible que se necesiten permisos adicionales, como bigquery.tables.getData, para acceder a los datos que escribes en la tabla.

En las siguientes funciones predefinidas de IAM, se incluyen los permisos bigquery.tables.create y bigquery.tables.updateData:

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

Las siguientes funciones predefinidas de IAM incluyen los permisos bigquery.jobs.create:

• bigquery.user
• bigquery.jobUser
• bigquery.admin

Además, si un usuario tiene permisos bigquery.datasets.create, se le otorga el acceso bigquery.dataOwner cuando crea un conjunto de datos. Con el acceso bigquery.dataOwner, el usuario puede crear y actualizar tablas en el conjunto de datos.

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

Crea una tabla agrupada 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 Google Cloud Console, ve a la página de BigQuery.

   Ir a la página de BigQuery

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

   Nota: La experiencia predeterminada es la vista previa de Cloud Console. Si hiciste clic en Hide preview features para ir a Cloud Console con disponibilidad general, realiza el siguiente paso: en la sección Recursos del panel de navegación, 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 Create table (Crear tabla), debajo de Source (Fuente), selecciona Empty table (Tabla vacía) en Create table from (Crear tabla desde).

   

6. En Destination (Destino), haz lo siguiente:

   • Para Nombre del conjunto de datos, selecciona el conjunto de datos apropiado y, en el campo Nombre de la tabla, escribe el nombre de la tabla que crearás.
   • Verifica que Tipo de tabla esté establecido en Tabla nativa.

7. En Esquema, ingresa la definición del esquema.

   • Ingresa la información del esquema de forma manual de la siguiente manera:

     • Habilita Editar como texto y, luego, ingresa el esquema de la tabla como un arreglo JSON.

       Nota: Para ver el esquema de una tabla existente en formato JSON, ingresa el siguiente comando en la herramienta de línea de comandos de bq: bq show --format=prettyjson dataset.table

     • Usa Agregar campo para ingresar el esquema de forma manual.

8. En Configuración de partición y agrupamiento en clústeres, selecciona Partición por campo y elige la columna DATE o TIMESTAMP (opcional). Esta opción no está disponible si el esquema no contiene una columna DATE o TIMESTAMP.

   Para crear una tabla particionada por tiempo de transferencia, selecciona Partición por tiempo de transferencia.

9. De forma opcional, en Filtro de partición (Partitioning filter), haz clic en la casilla de verificación Exigir filtro de partición (Require partition filter) a fin de solicitar a los usuarios que incluyan una cláusula WHERE que especifique las particiones que deben consultarse. Exigir un filtro de partición puede reducir los costos y mejorar el rendimiento. Para obtener más información, lee Consulta tablas particionadas.

10. Para Orden de agrupamiento en clústeres, ingresa entre uno y cuatro nombres de columna separados por comas.

11. Si deseas usar una clave de Cloud Key Management Service, haz clic en Opciones avanzadas y selecciona Clave administrada por el cliente en Encriptación. Si dejas establecida la configuración Clave administrada por Google, BigQuery encripta los datos en reposo.

12. Haz clic en Crear tabla.

Nota: Cuando creas una tabla particionada vacía mediante Cloud Console, no puedes agregar una etiqueta, una descripción ni un vencimiento de la tabla o de la partición. Puedes agregar estas propiedades opcionales cuando creas una tabla mediante la API o la herramienta de línea de comandos de bq.

Una vez que se crea la tabla, puedes actualizar el vencimiento, la descripción y las etiquetas de la tabla particionada. No puedes usar Cloud Console para agregar un vencimiento de la partición después de crear una tabla.

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 \
--time_partitioning_type=DAY \
--time_partitioning_field PARTITION_COLUMN \
--clustering_fields CLUSTER_COLUMNS \
--time_partitioning_expiration INTEGER2 \
--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 fecha de caducidad se evalúa según la hora UTC actual más el valor del número entero. Si configuras el tiempo de vencimiento de la tabla cuando creas una tabla particionada por el tiempo, se ignora la configuración de vencimiento de la tabla predeterminada del conjunto de datos. Si configuras este valor, la tabla y todas las particiones se borran después del lapso especificado.
• SCHEMA: 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.
• PARTITION_COLUMN: El nombre de la columna TIMESTAMP o DATE que se usa para crear una tabla particionada. Si creas una tabla particionada, no necesitas especificar la marca --time_partitioning_type=DAY.
• CLUSTER_COLUMNS: Una lista separada por comas de hasta cuatro columnas de agrupamiento en clústeres. La lista no puede contener espacios.
• INTEGER2: La duración predeterminada, en segundos, de las particiones de la tabla. No hay valor mínimo. El tiempo de vencimiento se evalúa según la fecha de la partición más el valor de número entero. El vencimiento de la partición es independiente del vencimiento de la tabla, pero no lo anula. Si configuras un vencimiento de partición que expire después del vencimiento de la tabla, prevalece el vencimiento de la tabla.
• 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: El nombre de la tabla particionada que creas.

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. La tabla es una tabla particionada (particionada por una columna TIMESTAMP). El vencimiento de la partición se establece en 86,400 segundos (1 día), el vencimiento de la tabla se establece en 2,592,000 (1 mes de 30 días), la descripción se establece en This is my clustered table y la etiqueta en organization:development. El comando usa la combinación de teclas -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 las particiones.

bq mk -t \
--expiration 2592000 \
--schema 'timestamp:timestamp,customer_id:string,transaction_amount:float' \
--time_partitioning_field timestamp \
--clustering_fields customer_id \
--time_partitioning_expiration 86400  \
--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 tabla es una tabla particionada en tiempo de transferencia. El vencimiento de la partición se establece en 259,200 segundos (3 días), la descripción se establece en This is my partitioned table y la etiqueta en organization:development. El comando usa la combinación de teclas -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 predeterminado, la tabla no se vencerá nunca, pero las particiones se vencerán en 3 días.

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

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

Una vez creada la tabla, puedes actualizar el vencimiento de tabla, el vencimiento de partición, la descripción y las etiquetas de la tabla particionada.

API

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

Python

Antes de probar esta muestra, 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. Si deseas obtener más información, consulta la documentación de referencia de la API de Python de BigQuery.

Ver en GitHubComentarios

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

Comienza a usarlo

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

Ver en GitHubComentarios

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 que se encuentran 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.

Ver en GitHubComentarios

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 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. Este método se analiza a continuación.
• 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.

Console

No puedes especificar opciones de agrupamiento en clústeres para una tabla de destino cuando realizas consultas de datos con Cloud Console, a menos que uses una declaración DDL. Para obtener más información, consulta Usa declaraciones de lenguaje de definición de datos.

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

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

Ver en GitHubComentarios

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 que se encuentran 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.

Ver en GitHubComentarios

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 esta muestra, 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. Si deseas obtener más información, consulta la documentación de referencia de la API de Python de BigQuery.

Ver en GitHubComentarios

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

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

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 acerca de las funciones y permisos, consulta los siguientes documentos:

• Descripción de las funciones en la documentación de IAM
• Funciones y permisos predefinidos de BigQuery
• Controla el acceso a los conjuntos de datos
• Controla el acceso a tablas y vistas
• Restringe el acceso con la seguridad a nivel de columnas de BigQuery

Usa tablas agrupadas en clústeres

Obtén información sobre las tablas agrupadas

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

• Usa Cloud Console.
• 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

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.

   

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.

SQL

En cuanto a las tablas agrupadas, puedes consultar la columna CLUSTERING_ORDINAL_POSITION en la vista INFORMATION_SCHEMA.COLUMNS a fin de recuperar información sobre las columnas de agrupamiento en clústeres de una tabla.

-- Set up a table with clustering.
CREATE TABLE myDataset.data (column1 INT64, column2 INT64)
PARTITION BY _PARTITIONDATE
CLUSTER BY column1, column2;

-- This query returns 1 for column1 and 2 for column2.
SELECT column_name, clustering_ordinal_position
FROM myDataset.INFORMATION_SCHEMA.COLUMNS;

Hay más metadatos de tabla disponibles a través de las vistas TABLES, TABLE_OPTIONS, COLUMNS y COLUMN_FIELD_PATH en INFORMATION_SCHEMA.

Haz una lista de tablas agrupadas 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 Cloud Console.
• 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. Para obtener más información sobre cómo enumerar tablas, consulta la sección sobre cómo mostrar una lista de tablas en un conjunto de datos.

Modifica la especificación de 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 no se pueden intercambiar con facilidad por otros métodos.

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

• Realiza una llamada al método de la 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.

Próximos pasos

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