Creare e utilizzare le tabelle in cluster

Questo documento descrive come creare e utilizzare le tabelle in cluster in in BigQuery. Per una panoramica del supporto delle tabelle in cluster in BigQuery, consulta Introduzione alle tabelle in cluster.

Creare tabelle in cluster

Puoi creare una tabella raggruppata utilizzando i seguenti metodi:

Denominazione delle tabelle

Quando crei una tabella in BigQuery, il nome deve essere unico per ogni set di dati. Il nome della tabella può:

  • Contenere caratteri per un totale massimo di 1024 byte UTF-8.
  • Contengono caratteri Unicode della categoria L (lettera), M (segno), N (numero), Pc (connettore, incluso il trattino basso), Pd (tratto), Zs (spazio). Per ulteriori informazioni, consulta la Categoria generale.

Di seguito sono riportati tutti gli esempi di nomi di tabelle validi: table 01, ग्राहक, 00_お客様, étudiant-01.

Precisazioni:

  • Per impostazione predefinita, i nomi delle tabelle sono sensibili alle maiuscole. mytable e MyTable possono coesistere nello stesso set di dati, a meno che non facciano parte di un set di dati con la sensibilità alle maiuscole disattivata.
  • Alcuni nomi di tabelle e prefissi dei nomi di tabelle sono riservati. Se viene visualizzato un messaggio di errore che indica che il nome o il prefisso della tabella è riservato, seleziona un nome diverso e riprova.

  • Se includi più operatori di punto (.) in una sequenza, lo stato duplicato vengono implicitamente eliminati.

    Ad esempio: project_name....dataset_name..table_name

    Diventa: project_name.dataset_name.table_name

Autorizzazioni obbligatorie

Per creare una tabella, devi disporre delle seguenti autorizzazioni IAM:

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

Inoltre, potresti richiedere l'autorizzazione bigquery.tables.getData per accedere ai dati che scrivi nella tabella.

Ciascuno dei seguenti ruoli IAM predefiniti include le autorizzazioni necessarie per creare una tabella:

  • roles/bigquery.dataEditor
  • roles/bigquery.dataOwner
  • roles/bigquery.admin (include l'autorizzazione bigquery.jobs.create)
  • roles/bigquery.user (include l'autorizzazione bigquery.jobs.create)
  • roles/bigquery.jobUser (include l'autorizzazione bigquery.jobs.create)

Inoltre, se disponi dell'autorizzazione bigquery.datasets.create, puoi creare e aggiornare le tabelle nei set di dati che crei.

Per ulteriori informazioni sui ruoli e sulle autorizzazioni IAM in BigQuery, consulta Ruoli e autorizzazioni predefiniti.

Crea una tabella in cluster vuota con una definizione di schema

Puoi specificare le colonne di clustering quando crei una tabella in BigQuery. Dopo aver creato la tabella, puoi modificare le colonne di clustering. Per maggiori dettagli, consulta Modificare la specifica di clustering.

Le colonne di clustering devono essere colonne di primo livello non ripetute e devono essere uno tra i seguenti tipi di dati semplici:

  • DATE
  • BOOLEAN
  • GEOGRAPHY
  • INTEGER
  • NUMERIC
  • BIGNUMERIC
  • STRING
  • TIMESTAMP
  • RANGE

Puoi specificare fino a quattro colonne di clustering. Quando specifichi più colonne, l'ordine delle colonne determina il modo in cui vengono ordinati i dati. Per Ad esempio, se la tabella è raggruppata in base alle colonne a, b e c, i dati vengono ordinati nello stesso ordine: prima per la colonna a, poi per la colonna b e infine per la colonna c Come best practice, posiziona prima la colonna filtrata o aggregata più di frequente.

L'ordine delle colonne di clustering influisce anche sul rendimento e sui prezzi delle query. Per ulteriori informazioni sulle best practice relative alle query per le tabelle in cluster, vedi Esecuzione di query su tabelle in cluster.

Per creare una tabella in cluster vuota con una definizione di schema:

Console

  1. Nella console Google Cloud, vai alla pagina BigQuery.

    Vai a BigQuery

  2. Nel riquadro Explorer, espandi il progetto e seleziona un set di dati.
  3. Nella sezione Informazioni set di dati, fai clic su Crea tabella.
  4. Nel riquadro Crea tabella, specifica i seguenti dettagli:
    1. Nella sezione Origine, seleziona Tabella vuota nell'elenco Crea tabella da.
    2. Nella sezione Destinazione, specifica i seguenti dettagli:
      1. In Set di dati, seleziona il set di dati in cui creare il tabella.
      2. Nel campo Tabella, inserisci il nome della tabella da creare.
      3. Verifica che il campo Tipo di tabella sia impostato su Tabella nativa.
    3. Nella sezione Schema, inserisci la definizione dello schema. Puoi inserire le informazioni sullo schema manualmente utilizzando uno dei seguenti utilizza i seguenti metodi:
      • Opzione 1: fai clic su Modifica come testo e incolla lo schema sotto forma di array JSON. Quando utilizzi un array JSON, generi lo schema utilizzando la stessa procedura utilizzata per creare un file di schema JSON. Puoi visualizzare lo schema di una tabella esistente in formato JSON inserendo quanto segue: : 
            bq show --format=prettyjson dataset.table
      • Opzione 2: fai clic su Aggiungi campo e inserisci lo schema della tabella. Specifica il Nome di ogni campo, Tipo, e Modalità.
    4. Per Ordine di clustering, inserisci da uno a quattro nomi di colonna separati da virgole.
    5. (Facoltativo) Nella sezione Opzioni avanzate, se vuoi utilizzare una chiave di crittografia gestita dal cliente, seleziona l'opzione Utilizza una chiave di crittografia gestita dal cliente (CMEK). Per impostazione predefinita, BigQuery cripta i contenuti archiviati inattivi dei clienti mediante una chiave di proprietà di Google.
    6. Fai clic su Crea tabella.

SQL

Utilizza l'istruzione DDL CREATE TABLE con l'opzione CLUSTER BY. L'esempio seguente crea un tabella in cluster denominata myclusteredtable in mydataset:

  1. Nella console Google Cloud, vai alla pagina BigQuery.

    Vai a BigQuery

  2. Nell'editor di query, inserisci la seguente istruzione:

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

  3. Fai clic su Esegui.

Per ulteriori informazioni su come eseguire query, consulta Eseguire una query interattiva.

bq

Utilizzare il comando bq mk con i seguenti flag:

  • --table (o la scorciatoia -t).
  • --schema. Puoi fornire la definizione dello schema della tabella in linea o utilizzare un file di schema JSON.
  • --clustering_fields. Puoi specificare fino a quattro colonne di raggruppamento.

I parametri facoltativi includono --expiration, --description, --time_partitioning_type, --time_partitioning_field, --time_partitioning_expiration, --destination_kms_key e --label.

Se crei una tabella in un progetto diverso da quello predefinito, aggiungi l'ID progetto al set di dati nel seguente formato: project_id:dataset.

--destination_kms_key non è stata dimostrata qui. Per informazioni su usando --destination_kms_key, vedi chiavi di crittografia gestite dal cliente.

Inserisci il comando seguente per creare una tabella clusterizzata vuota con una definizione dello schema:

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

Sostituisci quanto segue:

  • INTEGER1: la durata predefinita, in secondi, per nella tabella. Il valore minimo è 3600 secondi (un'ora). La scadenza viene valutata come l'ora UTC corrente più il valore intero. Se imposti la data e l'ora di scadenza della tabella quando la crei, l'impostazione predefinita della scadenza della tabella del set di dati viene ignorata. L'impostazione di questo valore elimina la tabella dopo il periodo di tempo specificato.
  • SCHEMA: una definizione di schema incorporata nel formato COLUMN:DATA_TYPE,COLUMN:DATA_TYPE o il percorso il file di schema JSON sulla macchina locale.
  • CLUSTER_COLUMNS: un elenco separato da virgole di massimo quattro colonne di clustering. L'elenco non può contenere spazi.
  • DESCRIPTION: una descrizione della tabella tra virgolette.
  • KEY:VALUE: la coppia chiave-valore che rappresenta una label. Puoi inserire più etichette utilizzando un elenco separato da virgole.
  • PROJECT_ID: il tuo ID progetto.
  • DATASET: un set di dati nel tuo progetto.
  • TABLE: il nome della tabella che stai creando.

Quando specifichi lo schema nella riga di comando, non puoi includere un'istruzione RECORD (STRUCT) non puoi includere una descrizione della colonna non può specificare la modalità della colonna. Per impostazione predefinita, tutte le modalità sono impostate su NULLABLE. A includi descrizioni, modalità e tipi di RECORD, fornisci uno schema JSON .

Esempi:

Inserisci il comando seguente per creare una tabella a cluster denominata myclusteredtable in mydataset nel tuo progetto predefinito. La tabella scadenza è impostata su 2.592.000 (1 mese di 30 giorni), la descrizione è This is my clustered table e l'etichetta è impostata su organization:development. Il comando utilizza la scorciatoia -t anziché --table.

Lo schema viene specificato in linea come: timestamp:timestamp,customer_id:string,transaction_amount:float. Il campo di clustering specificato customer_id viene utilizzato per raggruppare la tabella.

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

Inserisci il comando seguente per creare una tabella in cluster denominata myclusteredtable in myotherproject, non il progetto predefinito. La la descrizione è impostata su This is my clustered table e l'etichetta è impostata a organization:development. Il comando utilizza la scorciatoia -t anziché --table. Questo comando non specifica una scadenza per la tabella. Se il set di dati ha una scadenza predefinita per la tabella, viene applicata. Se il set di dati non ha valori predefiniti scadenza, la tabella non scade mai.

Lo schema è specificato in un file JSON locale: /tmp/myschema.json. La Il campo customer_id viene utilizzato per raggruppare la tabella.

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

Dopo aver creato la tabella, puoi aggiornarne la descrizione e le etichette.

Terraform

Utilizza la risorsa google_bigquery_table.

Per eseguire l'autenticazione in BigQuery, configura il valore predefinito dell'applicazione Credenziali. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.

L'esempio seguente crea una tabella denominata mytable raggruppata sulle colonne ID e 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

}

Per applicare la configurazione Terraform in un progetto Google Cloud, completa i passaggi nelle seguenti sezioni.

Prepara Cloud Shell

  1. Avvia Cloud Shell.

  2. Imposta il progetto Google Cloud predefinito dove vuoi applicare le configurazioni Terraform.

    Devi eseguire questo comando una sola volta per progetto e puoi farlo in qualsiasi directory.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Le variabili di ambiente vengono sostituite se imposti valori espliciti in Terraform di configurazione del deployment.

Prepara la directory

Ogni file di configurazione Terraform deve avere una directory dedicata (inoltre chiamato modulo principale).

  1. In Cloud Shell, crea una directory e un nuovo file al suo interno. Il nome file deve contenere .tf, ad esempio main.tf. In questo tutorial, il file è denominato main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Se stai seguendo un tutorial, puoi copiare il codice campione in ogni sezione o passaggio.

    Copia il codice campione nel nuovo oggetto main.tf.

    Facoltativamente, copia il codice da GitHub. Opzione consigliata quando lo snippet Terraform fa parte di una soluzione end-to-end.

  3. Esamina e modifica i parametri di esempio da applicare al tuo ambiente.
  4. Salva le modifiche.
  5. Inizializza Terraform. Devi eseguire questa operazione una sola volta per directory. 
    terraform init

    Facoltativamente, per utilizzare la versione più recente del provider Google, includi -upgrade : 

    terraform init -upgrade

Applica le modifiche

  1. Rivedi la configurazione e verifica che le risorse che Terraform creerà o che l'aggiornamento soddisfi le tue aspettative: 
    terraform plan

    Apporta le correzioni necessarie alla configurazione.

  2. Applica la configurazione di Terraform eseguendo il seguente comando e inserendo yes al prompt: 
    terraform apply

    Attendi che Terraform mostri il messaggio "Applicazione completata".

  3. Apri il progetto Google Cloud per visualizzare i risultati. Nella console Google Cloud, vai alle risorse nell'interfaccia utente per assicurarti che Terraform le abbia create o aggiornate.

API

Chiama il tables.insert con una risorsa di tabella definita che specifica la proprietà clustering.fields e la proprietà schema.

Python

Prima di provare questo esempio, segui le istruzioni per la configurazione di Python nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Python.

Per autenticarti a BigQuery, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client. 

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

Vai

Prima di provare questo esempio, segui le istruzioni di configurazione Go riportate nella guida rapida all'utilizzo di BigQuery con le librerie client. Per ulteriori informazioni, consulta API Go BigQuery documentazione di riferimento.

Per autenticarti a BigQuery, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client. 

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

Prima di provare questo esempio, segui le istruzioni per la configurazione di Java nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API Java BigQuery documentazione di riferimento.

Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client. 

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 tabella in cluster dal risultato di una query

Esistono due modi per creare una tabella in cluster a partire dal risultato di una query:

Puoi creare una tabella in cluster eseguendo una query su una tabella partizionata non tabella partizionata. Non puoi modificare una tabella esistente in una tabella cluster utilizzando i risultati di query.

Quando crei una tabella in cluster da un risultato di query, devi utilizzare SQL standard. Al momento, l'SQL precedente non è supportato per le query sulle tabelle cluster o per la scrittura dei risultati delle query nelle tabelle cluster.

SQL

Per creare una tabella in cluster a partire dal risultato di una query, utilizza CREATE TABLE Istruzione DDL con l'opzione CLUSTER BY. L'esempio seguente crea una nuova tabella raggruppata in base a customer_id mediante l'esecuzione di query su una tabella non in cluster esistente:

  1. Nella console Google Cloud, vai alla pagina BigQuery.

    Vai a BigQuery

  2. Nell'editor di query, inserisci la seguente istruzione:

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

  3. Fai clic su Esegui.

Per ulteriori informazioni su come eseguire query, consulta Eseguire una query interattiva.

bq

Inserisci il comando seguente per creare una nuova destinazione in cluster tabella dal risultato di una query:

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

Sostituisci quanto segue:

  • LOCATION: il nome della tua località. Il flag --location è facoltativo. Ad esempio, se utilizzi BigQuery nella regione di Tokyo, puoi impostare il valore del flag su asia-northeast1. Tu puoi impostare un valore predefinito per la località utilizzando file.bigqueryrc.
  • QUERY: una query con la sintassi GoogleSQL. Al momento, non puoi utilizzare SQL precedente per eseguire query sulle tabelle in cluster o per scrivere i risultati delle query nelle tabelle in cluster. La query può contenere un CREATE TABLE DDL che specifica le opzioni per la creazione della tabella in cluster. Puoi utilizzare il DDL anziché specificare i singoli flag della riga di comando.

Esempi:

Inserisci il comando seguente per scrivere i risultati della query in un cluster tabella di destinazione denominata myclusteredtable in mydataset. mydataset si trova nel tuo progetto predefinito. La query recupera i dati da una tabella non partizionata: mytable. La colonna customer_id della tabella viene utilizzata per raggruppare le tabella. La colonna timestamp della tabella viene utilizzata per creare una tabella partizionata.

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

API

Per salvare i risultati della query in una tabella in cluster: chiama il metodo jobs.insert, configurare un query job, e includi un CREATE TABLE DDL che crea la tabella in cluster.

Specifica la tua località nella proprietà location del jobReference del risorse di lavoro.

Creare una tabella raggruppata quando carichi i dati

Puoi creare una tabella raggruppata specificando le colonne di clustering quando carichi i dati in una nuova tabella. Non è necessario creare una tabella vuota prima di caricarvi i dati. Puoi creare la tabella in cluster e caricare i dati nel tempo.

Per ulteriori informazioni sul caricamento dei dati, consulta Introduzione al caricamento dei dati in BigQuery.

Per definire il clustering durante la definizione di un job di caricamento:

SQL

Utilizza l'istruzione LOAD DATA. L'esempio seguente carica i dati AVRO per creare una tabella partizionata dal campo transaction_date e raggruppati in base al campo customer_id. Inoltre, configura le partizioni in modo che scadano dopo tre giorni.

  1. Nella console Google Cloud, vai alla pagina BigQuery.

    Vai a BigQuery

  2. Nell'editor di query, inserisci la seguente istruzione:

    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. Fai clic su Esegui.

Per ulteriori informazioni su come eseguire query, consulta Eseguire una query interattiva.

API

Per definire una configurazione di clustering durante la creazione di una tabella tramite un job di caricamento, puoi compilare le proprietà Clustering per la tabella.

Vai

Prima di provare questo esempio, segui le istruzioni per la configurazione di Go nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API Go BigQuery documentazione di riferimento.

Per autenticarti a BigQuery, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client. 

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

Prima di provare questo esempio, segui le istruzioni di configurazione Java riportate nella guida rapida all'utilizzo di BigQuery con le librerie client. Per ulteriori informazioni, consulta API Java BigQuery documentazione di riferimento.

Per autenticarti a BigQuery, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client. 

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

Prima di provare questo esempio, segui le istruzioni per la configurazione di Python nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Python.

Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client. 

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

Controlla l'accesso alle tabelle in cluster

Per configurare l'accesso a tabelle e viste, puoi concedere a ruolo IAM a un'entità ai seguenti livelli, elencati in ordine delle risorse consentite (dalla più grande alla più piccola):

Puoi anche limitare l'accesso ai dati all'interno delle tabelle utilizzando quanto segue: metodo:

L'accesso con qualsiasi risorsa protetta da IAM è cumulativo. Ad esempio, se un'entità non ha accesso a un livello elevato, come un progetto, puoi concederle l'accesso a livello di set di dati, in modo che possa accedere alle tabelle e alle visualizzazioni al suo interno. Analogamente, se l'entità non ha accesso a livello elevato o a livello di set di dati, puoi concederle l'accesso a livello di tabella o vista.

Concessione di ruoli IAM a un livello superiore in Google Cloud gerarchia delle risorse a livello di progetto, cartella o organizzazione, concede all'entità l'accesso a un di un'ampia gamma di risorse. Ad esempio, concedere un ruolo a un'entità nel progetto assegna a quell'entità le autorizzazioni che si applicano a tutti i set di dati nell'area progetto.

La concessione di un ruolo a livello di set di dati specifica le operazioni a cui è soggetta un'entità possono essere eseguite su tabelle e viste in quello specifico set di dati, anche se l'entità non ha accesso a un livello superiore. Per informazioni sulla configurazione controlli dell'accesso a livello di set di dati, consulta Controllo dell'accesso ai set di dati.

La concessione di un ruolo a livello di tabella o vista specifica le operazioni che un'entità è autorizzata a eseguire su tabelle e viste specifiche, anche se l'entità non ha accesso a un livello superiore. Per informazioni sulla configurazione dei controlli di accesso a livello di tabella, consulta Controllo dell'accesso a tabelle e viste.

Puoi anche creare ruoli IAM personalizzati. Se crei un ruolo personalizzato, le autorizzazioni che concedi dipendono dall'impostazione le operazioni che deve essere eseguita dall'entità.

Non puoi impostare un rifiuto su qualsiasi risorsa protetta o IAM.

Per saperne di più su ruoli e autorizzazioni, consulta Informazioni sui ruoli nella documentazione IAM e Ruoli e autorizzazioni IAM di BigQuery.

Utilizza tabelle in cluster

Ottieni informazioni sulle tabelle in cluster

Puoi ottenere informazioni sulle tabelle nei seguenti modi:

  • Utilizzo della console Google Cloud.
  • Utilizzo del comando bq show dello strumento a riga di comando bq.
  • Chiamata al metodo dell'API tables.get.
  • Eseguire query sulle visualizzazioni INFORMATION_SCHEMA.

Autorizzazioni obbligatorie

Per ottenere informazioni sulle tabelle, devi disporre almeno delle autorizzazioni bigquery.tables.get. I seguenti ruoli IAM predefiniti includono le autorizzazioni bigquery.tables.get:

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

Inoltre, se un utente dispone delle autorizzazioni bigquery.datasets.create, quando crea un set di dati e gli viene concesso l'accesso bigquery.dataOwner. L'accesso bigquery.dataOwner consente all'utente di ottenere informazioni sulle tabelle di un set di dati.

Per ulteriori informazioni sui ruoli e sulle autorizzazioni IAM in BigQuery, consulta Ruoli e autorizzazioni predefiniti.

Visualizza le informazioni sulle tabelle in cluster

Per visualizzare informazioni su una tabella cluster:

Console

  1. Nella console Google Cloud, vai al riquadro Risorse. Fai clic sul nome del set di dati per espanderlo, quindi fai clic sul nome della tabella che vuoi visualizzare.

  2. Fai clic su Dettagli. In questa pagina vengono visualizzati i seguenti tra cui le colonne di clustering.

    Dettagli della tabella.

SQL

Per le tabelle in cluster, puoi eseguire query sulla colonna CLUSTERING_ORDINAL_POSITION nella vista INFORMATION_SCHEMA.COLUMNS per trovare l'offset indicizzato a 1 della colonna all'interno del clustering della tabella colonne:

  1. Nella console Google Cloud, vai alla pagina BigQuery.

    Vai a BigQuery

  2. Nell'editor di query, inserisci la seguente istruzione:

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

  3. Fai clic su Esegui.

Per ulteriori informazioni su come eseguire query, consulta Eseguire una query interattiva.

La posizione ordinale di clustering è 1 per column1 e 2 per column2. Altri metadati della tabella sono disponibili tramite le visualizzazioni TABLES, TABLE_OPTIONS, COLUMNS e COLUMN_FIELD_PATH in INFORMATION_SCHEMA.

bq

Esegui il comando bq show per visualizzare tutte le informazioni della tabella. Utilizza la --schema per visualizzare solo le informazioni sullo schema della tabella. --format per controllare l'output.

Se ricevi informazioni su una tabella in un progetto diverso da progetto predefinito, aggiungi l'ID progetto al set di dati nel seguente formato: project_id:dataset.

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

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto
  • DATASET: il nome del set di dati
  • TABLE: il nome della tabella

Esempi:

Inserisci il seguente comando per visualizzare tutte le informazioni su myclusteredtable in mydataset. mydataset nel progetto predefinito.

bq show --format=prettyjson mydataset.myclusteredtable

L'output dovrebbe essere simile al seguente: 

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

API

Chiama il metodo bigquery.tables.get e fornisci eventuali parametri pertinenti.

Elenca le tabelle in cluster in un set di dati

Puoi elencare le tabelle raggruppate nei set di dati nei seguenti modi:

  • Utilizzo della console Google Cloud.
  • Viene utilizzato il comando bq ls dello strumento a riga di comando bq.
  • Chiamata all'API tables.list .
  • Utilizzare le librerie client.
  • Esecuzione di una query sulla colonna CLUSTERING_ORDINAL_POSITION nella INFORMATION_SCHEMA.COLUMNS visualizzazione.

Le autorizzazioni necessarie per elencare le tabelle raggruppate e i passaggi per elencarle sono le stesse delle tabelle standard. Per ulteriori informazioni sulle tabelle di elenco, consulta Elencare le tabelle in un set di dati.

Modificare la specifica del clustering

Puoi modificare o rimuovere le specifiche di clustering di una tabella oppure modificare l'insieme di colonne raggruppate in una tabella raggruppata. Questo metodo di aggiornamento del set di colonne di clustering è utile per le tabelle che utilizzano inserimenti in streaming continuo perché non possono essere scambiate facilmente con altri metodi.

Segui questi passaggi per applicare una nuova specifica di clustering alle applicazioni partizionate.

  1. Nello strumento bq, aggiorna la specifica di clustering della tabella in modo che corrisponda al nuovo clustering:

     bq update --clustering_fields=CLUSTER_COLUMN DATASET.ORIGINAL_TABLE

    Sostituisci quanto segue:

    • CLUSTER_COLUMN: la colonna su cui esegui il clustering, ad esempio mycolumn
    • DATASET: il nome del set di dati contenente la tabella, ad esempio mydataset
    • ORIGINAL_TABLE: il nome della tabella originale, ad esempio mytable

    Puoi anche chiamare il metodo API tables.update o tables.patch per modificare la specifica di clustering.

  2. Per raggruppare tutte le righe in base alla nuova specifica di clustering, esegui la seguente istruzione UPDATE:

    UPDATE DATASET.ORIGINAL_TABLE SET CLUSTER_COLUMN=CLUSTER_COLUMN WHERE true

Sicurezza delle tabelle

Per controllare l'accesso alle tabelle in BigQuery, consulta Introduzione ai controlli di accesso alle tabelle.

Passaggi successivi