Membuat dan menggunakan tabel yang dikelompokkan

Dokumen ini menjelaskan cara membuat dan menggunakan tabel yang dikelompokkan di BigQuery. Untuk ringkasan dukungan tabel yang dikelompokkan di BigQuery, lihat Pengantar tabel yang dikelompokkan.

Membuat tabel yang dikelompokkan

Anda dapat membuat tabel yang dikelompokkan menggunakan metode berikut:

• Membuat tabel dari hasil kueri:

  • Jalankan pernyataan CREATE TABLE AS SELECT DDL.
  • Jalankan kueri yang membuat tabel tujuan yang dikelompokkan.

• Menggunakan pernyataan CREATE TABLE DDL dengan klausa CLUSTER BY yang berisi clustering_column_list.

• Menjalankan perintah bq mk alat command line bq.

• Melakukan panggilan ke metode API tables.insert.

• Memuat data ke BigQuery.

• Menggunakan library klien.

Penamaan tabel

Saat Anda membuat tabel di BigQuery, nama tabel per set data harus unik. Nama tabel dapat:

• Berisi karakter dengan total hingga 1.024 byte UTF-8.
• Berisi karakter Unicode dalam kategori L (huruf), M (tanda), N (angka), Pc (penghubung, termasuk garis bawah), Pd (tanda pisah), Zs (spasi). Untuk informasi selengkapnya, lihat Kategori Umum.

Berikut adalah contoh nama tabel yang valid: table 01, ग्राहक, 00_お客様, étudiant-01.

Peringatan:

• Nama tabel peka huruf besar/kecil secara default. mytable dan MyTable dapat berada dalam set data yang sama, kecuali jika keduanya merupakan bagian dari set data yang tidak peka huruf besar/kecil.
• Beberapa nama tabel dan awalan nama tabel dicadangkan. Jika Anda menerima error yang menyatakan bahwa nama tabel atau awalan telah dicadangkan, pilih nama lain dan coba lagi.

• Jika Anda menyertakan beberapa operator titik (.) secara berurutan, operator duplikat tersebut akan dihapus secara implisit.

  Misalnya, contoh ini: project_name....dataset_name..table_name

  Menjadi seperti ini: project_name.dataset_name.table_name

Izin yang diperlukan

Untuk membuat tabel, Anda memerlukan izin IAM berikut:

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

Selain itu, Anda mungkin memerlukan izin bigquery.tables.getData untuk mengakses data yang Anda tulis ke tabel.

Setiap peran IAM yang telah ditetapkan berikut menyertakan izin yang Anda perlukan untuk membuat tabel:

• roles/bigquery.dataEditor
• roles/bigquery.dataOwner
• roles/bigquery.admin (termasuk izin bigquery.jobs.create)
• roles/bigquery.user (termasuk izin bigquery.jobs.create)
• roles/bigquery.jobUser (termasuk izin bigquery.jobs.create)

Selain itu, jika memiliki izin bigquery.datasets.create, Anda dapat membuat dan memperbarui tabel di set data yang Anda buat.

Untuk informasi selengkapnya tentang peran dan izin IAM dalam BigQuery, baca Peran dan izin bawaan.

Membuat tabel kosong yang dikelompokkan dengan definisi skema

Anda menentukan kolom pengelompokkan saat membuat tabel di BigQuery. Setelah tabel dibuat, Anda dapat mengubah kolom pengelompokkan; baca artikel Mengubah spesifikasi pengelompokan untuk detailnya.

Kolom pengelompokan harus berupa kolom tingkat atas yang tidak berulang, dan harus berupa salah satu dari jenis data berikut:

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

Anda dapat menentukan hingga empat kolom pengelompokkan. Ketika Anda menentukan beberapa kolom, urutan kolom menentukan bagaimana data diurutkan. Misalnya, jika tabel dikelompokkan menurut kolom a, b, dan c, data akan diurutkan dalam urutan yang sama: pertama menurut kolom a, lalu menurut kolom b, dan kemudian menurut kolom c. Sebagai praktik terbaik, tempatkan kolom yang paling sering difilter atau digabungkan terlebih dahulu.

Urutan kolom pengelompokkan juga memengaruhi performa kueri dan harga. Untuk informasi selengkapnya tentang praktik terbaik kueri untuk tabel yang dikelompokkan, lihat Membuat kueri tabel yang dikelompokkan.

Untuk membuat tabel kosong yang dikelompokkan dengan definisi skema:

Konsol

1. Di konsol Google Cloud, buka halaman BigQuery.

   Buka BigQuery

2. Di panel Explorer, luaskan project Anda, lalu pilih set data.
3. Di bagian Dataset info, klik Create table.
4. Di panel Create table, tentukan detail berikut:
1. Di bagian Source, pilih Empty table dalam daftar Create table from.
2. Di bagian Destination, tentukan detail berikut:
   1. Untuk Dataset, pilih set data tempat Anda ingin membuat tabel.
   2. Di kolom Table, masukkan nama tabel yang ingin Anda buat.
   3. Pastikan kolom Table type disetel ke Native table.
3. Di bagian Schema, masukkan definisi skema. Anda dapat memasukkan informasi skema secara manual menggunakan salah satu metode berikut:
   • Opsi 1: Klik Edit as text dan tempelkan skema dalam bentuk array JSON. Saat menggunakan array JSON, Anda menghasilkan skema menggunakan proses yang sama seperti membuat file skema JSON. Anda dapat melihat skema tabel yang ada dalam format JSON dengan memasukkan perintah berikut:

         bq show --format=prettyjson dataset.table
         

   • Opsi 2: Klik Add field, lalu masukkan skema tabel. Tentukan Name, Type, dan Mode untuk setiap kolom.
4. Untuk Clustering order, masukkan antara satu dan empat nama kolom yang dipisahkan koma.
5. Opsional: Di bagian Advanced options, jika ingin menggunakan kunci enkripsi yang dikelola pelanggan, pilih opsi Use a customer-managed encryption key (CMEK). Secara default, BigQuery mengenkripsi konten pelanggan yang disimpan dalam penyimpanan dengan menggunakan kunci yang dimiliki dan dikelola Google.
6. Klik Create table.

SQL

Gunakan perintah Pernyataan CREATE TABLE DDL dengan opsi CLUSTER BY. Contoh berikut akan membuat tabel yang dikelompokkan dengan nama myclusteredtable di mydataset:

1. Di Konsol Google Cloud, buka halaman BigQuery.

   Buka BigQuery

2. Di editor kueri, masukkan pernyataan berikut:

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

3. Klik Run.

Untuk informasi selengkapnya tentang cara menjalankan kueri, lihat Menjalankan kueri interaktif.

bq

Gunakan perintah bq mk dengan flag berikut:

• --table (atau pintasan -t).
• --schema. Anda dapat menyediakan definisi skema tabel secara inline atau menggunakan file skema JSON.
• --clustering_fields. Anda dapat menentukan hingga empat kolom pengelompokkan.

Parameter opsional mencakup --expiration, --description, --time_partitioning_type, --time_partitioning_field, --time_partitioning_expiration, --destination_kms_key, dan --label.

Jika Anda membuat tabel dalam project selain project default Anda, tambahkan project ID ke set data dalam format berikut: project_id:dataset.

--destination_kms_key tidak ditunjukkan di sini. Untuk informasi tentang penggunaan --destination_kms_key, lihat kunci enkripsi yang dikelola pelanggan.

Masukkan perintah berikut untuk membuat tabel kosong yang dikelompokkan dengan definisi skema:

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

Ganti yang berikut ini:

• INTEGER1: masa aktif default, dalam detik, untuk tabel. Nilai minimum adalah 3.600 detik (satu jam). Waktu habis masa berlaku dievaluasi ke waktu UTC saat ini ditambah dengan nilai bilangan bulat. Jika Anda menetapkan waktu habis masa berlaku tabel saat membuat tabel, setelan habis masa berlaku tabel default set data akan diabaikan. Menyetel nilai ini akan menghapus tabel setelah waktu yang ditentukan.
• SCHEMA: definisi skema inline dalam format COLUMN:DATA_TYPE,COLUMN:DATA_TYPE atau jalur ke file skema JSON di mesin lokal Anda.
• CLUSTER_COLUMNS: daftar yang dipisahkan koma untuk maksimal empat kolom pengelompokkan. Daftar tidak boleh berisi spasi.
• DESCRIPTION: deskripsi tabel, dalam tanda kutip.
• KEY:VALUE: pasangan nilai kunci yang mewakili label. Anda dapat memasukkan beberapa label menggunakan daftar yang dipisahkan koma.
• PROJECT_ID: project ID Anda.
• DATASET: set data di project Anda.
• TABLE: nama tabel yang Anda buat.

Saat menentukan skema di command line, Anda tidak dapat menyertakan jenis RECORD (STRUCT), Anda tidak dapat menyertakan deskripsi kolom, dan Anda tidak dapat menentukan mode kolom. Semua mode ditetapkan secara default ke NULLABLE. Untuk menyertakan deskripsi, mode, dan jenis RECORD, berikan file skema JSON sebagai gantinya.

Contoh:

Masukkan perintah berikut untuk membuat tabel yang dikelompokkan bernama myclusteredtable di mydataset di project default Anda. Masa berlaku tabel ditetapkan ke 2.592.000 (1 bulan dalam 30 hari), deskripsi ditetapkan ke This is my clustered table, dan label ditetapkan ke organization:development. Perintah tersebut menggunakan pintasan -t, bukan --table.

Skema ditentukan secara inline sebagai: timestamp:timestamp,customer_id:string,transaction_amount:float. Kolom pengelompokan yang ditentukan customer_id digunakan untuk mengelompokkan tabel.

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

Masukkan perintah berikut untuk membuat tabel yang dikelompokkan bernama myclusteredtable di myotherproject, bukan project default Anda. Deskripsi ditetapkan ke This is my clustered table, dan label ditetapkan ke organization:development. Perintah tersebut menggunakan pintasan -t, bukan --table. Perintah ini tidak menentukan masa berlaku tabel. Jika set data memiliki masa berlaku tabel default, masa berlaku tabel tersebut akan diterapkan. Jika set data tidak memiliki akhir masa berlaku tabel default, tabel tersebut tidak akan pernah memiliki tanggal habis masa berlaku.

Skema ini ditentukan dalam file JSON lokal: /tmp/myschema.json. Kolom customer_id digunakan untuk mengelompokkan tabel.

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

Setelah tabel dibuat, Anda dapat memperbarui deskripsi dan label tabel.

Terraform

Gunakan resource google_bigquery_table.

Catatan: Untuk membuat objek BigQuery menggunakan Terraform, Anda harus mengaktifkan Cloud Resource Manager API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Contoh berikut membuat tabel bernama mytable yang dikelompokkan pada kolom ID dan 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

}

Untuk menerapkan konfigurasi Terraform di project Google Cloud, selesaikan langkah-langkah di bagian berikut.

Menyiapkan Cloud Shell

1. Luncurkan Cloud Shell.

2. Tetapkan project Google Cloud default tempat Anda ingin menerapkan konfigurasi Terraform.

   Anda hanya perlu menjalankan perintah ini sekali per project, dan dapat dijalankan di direktori mana pun.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Variabel lingkungan akan diganti jika Anda menetapkan nilai eksplisit dalam file konfigurasi Terraform.

Menyiapkan direktori

Setiap file konfigurasi Terraform harus memiliki direktorinya sendiri (juga disebut modul root).

1. Di Cloud Shell, buat direktori dan file baru di dalam direktori tersebut. Nama file harus memiliki ekstensi .tf—misalnya main.tf. Dalam tutorial ini, file ini disebut sebagai main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. Jika mengikuti tutorial, Anda dapat menyalin kode contoh di setiap bagian atau langkah.

   Salin kode contoh ke dalam main.tf yang baru dibuat.

   Atau, salin kode dari GitHub. Tindakan ini direkomendasikan jika cuplikan Terraform adalah bagian dari solusi menyeluruh.

3. Tinjau dan ubah contoh parameter untuk diterapkan pada lingkungan Anda.
4. Simpan perubahan Anda.
5. Lakukan inisialisasi Terraform. Anda hanya perlu melakukan ini sekali per direktori.

   terraform init

   Secara opsional, untuk menggunakan versi penyedia Google terbaru, sertakan opsi -upgrade:

   terraform init -upgrade

Menerapkan perubahan

1. Tinjau konfigurasi dan pastikan resource yang akan dibuat atau diupdate oleh Terraform sesuai yang Anda inginkan:

   terraform plan

   Koreksi konfigurasi jika diperlukan.

2. Terapkan konfigurasi Terraform dengan menjalankan perintah berikut dan memasukkan yes pada prompt:

   terraform apply

   Tunggu hingga Terraform menampilkan pesan "Apply complete!".

3. Buka project Google Cloud Anda untuk melihat hasilnya. Di Konsol Google Cloud, buka resource Anda di UI untuk memastikan bahwa Terraform telah membuat atau mengupdatenya.

Catatan: Contoh Terraform biasanya mengasumsikan bahwa API yang diperlukan diaktifkan di project Google Cloud Anda.

API

Panggil metode tables.insert dengan resource tabel yang ditentukan yang menentukan properti clustering.fields dan properti schema.

Python

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Python API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Go di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Go API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Java di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Java API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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());
    }
  }
}

Membuat tabel yang dikelompokkan dari hasil kueri

Ada dua cara untuk membuat tabel yang dikelompokkan dari hasil kueri:

• Tulis hasilnya ke tabel tujuan baru dan tentukan kolom pengelompokkan.
• Dengan menggunakan pernyataan CREATE TABLE AS SELECT DDL. Untuk informasi selengkapnya tentang metode ini, lihat Membuat tabel yang dikelompokkan dari hasil kueri di halaman Menggunakan pernyataan bahasa definisi data.

Anda dapat membuat tabel yang dikelompokkan dengan membuat kueri tabel berpartisi atau tabel yang tidak berpartisi. Anda tidak dapat mengubah tabel yang ada menjadi tabel yang dikelompokkan menggunakan hasil kueri.

Saat membuat tabel yang dikelompokkan dari hasil kueri, Anda harus menggunakan SQL standar. Saat ini, legacy SQL tidak didukung untuk membuat kueri tabel yang dikelompokkan atau untuk menulis hasil kueri ke tabel yang dikelompokkan.

SQL

Untuk membuat tabel yang dikelompokkan dari hasil kueri, gunakan pernyataan CREATE TABLE DDL dengan opsi CLUSTER BY. Contoh berikut membuat tabel baru yang dikelompokkan menurut customer_id dengan membuat kueri tabel tidak dikelompokkan yang ada:

1. Di Konsol Google Cloud, buka halaman BigQuery.

   Buka BigQuery

2. Di editor kueri, masukkan pernyataan berikut:

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

3. Klik Run.

Untuk informasi selengkapnya tentang cara menjalankan kueri, lihat Menjalankan kueri interaktif.

bq

Masukkan perintah berikut untuk membuat tabel tujuan baru yang dikelompokkan dari hasil kueri:

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

Ganti yang berikut ini:

• LOCATION: nama lokasi Anda. Flag --location bersifat opsional. Misalnya, jika menggunakan BigQuery di region Tokyo, Anda dapat menetapkan nilai flag ke asia-northeast1. Anda dapat menetapkan nilai default untuk lokasi menggunakan file .bigqueryrc.
• QUERY: kueri dalam sintaksis GoogleSQL. Saat ini, Anda tidak dapat menggunakan legacy SQL untuk membuat kueri tabel yang dikelompokkan atau menulis hasil kueri ke tabel yang dikelompokkan. Kueri dapat berisi pernyataan CREATE TABLE DDL yang menentukan opsi untuk membuat tabel yang dikelompokkan. Anda dapat menggunakan DDL, bukan menentukan flag command line satu per satu.

Contoh:

Masukkan perintah berikut untuk menulis hasil kueri ke tabel tujuan yang dikelompokkan bernama myclusteredtable di mydataset. mydataset ada dalam project default Anda. Kueri tersebut mengambil data dari tabel yang tidak berpartisi: mytable. Kolom customer_id tabel digunakan untuk mengelompokkan tabel. Kolom timestamp tabel digunakan untuk membuat tabel berpartisi.

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

API

Untuk menyimpan hasil kueri ke tabel yang dikelompokkan, panggil metode jobs.insert, konfigurasi tugas query, dan sertakan pernyataan CREATE TABLE DDL yang membuat tabel yang dikelompokkan.

Tentukan lokasi Anda di properti location di bagian jobReference di resource tugas.

Membuat tabel yang dikelompokkan saat Anda memuat data

Anda dapat membuat tabel yang dikelompokkan dengan menentukan kolom pengelompokan saat memuat data ke tabel baru. Anda tidak perlu membuat tabel kosong sebelum memuat data ke dalamnya. Anda dapat membuat tabel yang dikelompokkan dan memuat data secara bersamaan.

Untuk informasi selengkapnya tentang pemuatan data, lihat Pengantar pemuatan data ke BigQuery.

Untuk menentukan pengelompokan saat menentukan tugas pemuatan:

SQL

Gunakan pernyataan LOAD DATA. Contoh berikut memuat data AVRO untuk membuat tabel yang dipartisi berdasarkan kolom transaction_date dan dikelompokkan menurut kolom customer_id. Perintah ini juga mengonfigurasi agar masa berlaku partisi berakhir setelah tiga hari.

1. Di Konsol Google Cloud, buka halaman BigQuery.

   Buka BigQuery

2. Di editor kueri, masukkan pernyataan berikut:

   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. Klik Run.

Untuk informasi selengkapnya tentang cara menjalankan kueri, lihat Menjalankan kueri interaktif.

API

Untuk menentukan konfigurasi pengelompokan saat membuat tabel melalui tugas pemuatan, Anda dapat mengisi properti Clustering untuk tabel tersebut.

Go

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Go di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Go API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Java di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Java API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Python API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

Mengontrol akses ke tabel yang dikelompokkan

Untuk mengonfigurasi akses ke tabel dan tabel virtual, Anda dapat memberikan peran IAM ke entity di tingkat berikut, yang tercantum sesuai urutan rentang resource yang diizinkan (terbesar hingga terkecil):

• tingkat tinggi dalam hierarki resource Google Cloud, seperti tingkat project, folder, atau organisasi
• tingkat set data
• tingkat tabel atau tabel virtual

Anda juga dapat membatasi akses data dalam tabel menggunakan metode berikut:

• keamanan tingkat kolom
• penyamaran data kolom
• keamanan tingkat baris

Akses dengan resource apa pun yang dilindungi oleh IAM bersifat tambahan. Misalnya, jika suatu entity tidak memiliki akses di tingkat tinggi seperti project, Anda dapat memberikan akses ke entity tersebut di tingkat set data, lalu entity akan memiliki akses ke tabel dan tabel virtual dalam set data. Demikian pula, jika entity tidak memiliki akses di tingkat tinggi atau tingkat set data, Anda dapat memberikan akses ke entity di tingkat tabel atau tabel virtual.

Memberikan peran IAM di tingkat yang lebih tinggi dalam hierarki resource Google Cloud seperti tingkat project, folder, atau organisasi akan memberi entity akses ke berbagai resource. Misalnya, memberikan peran ke suatu entity di tingkat project akan memberikan izin entity yang berlaku untuk semua set data di seluruh project.

Memberikan peran di tingkat set data akan menentukan operasi yang diizinkan untuk dilakukan oleh entity di tabel dan tabel virtual di set data tertentu tersebut, meskipun entity tidak memiliki akses di tingkat yang lebih tinggi. Untuk informasi tentang cara mengonfigurasi kontrol akses tingkat set data, baca Mengontrol akses ke set data.

Memberikan peran di tingkat tabel atau tabel virtual akan menentukan operasi yang diizinkan untuk dilakukan oleh entity pada tabel dan tabel virtual tertentu, meskipun jika entity tersebut tidak memiliki akses di tingkat yang lebih tinggi. Untuk informasi tentang cara mengonfigurasi kontrol akses tingkat tabel, lihat Mengontrol akses ke tabel dan tabel virtual.

Anda juga dapat membuat peran khusus IAM. Jika Anda membuat peran khusus, izin yang diberikan bergantung pada operasi tertentu yang Anda inginkan untuk dapat dilakukan oleh entity.

Anda tidak dapat menetapkan izin "tolak" pada resource apa pun yang dilindungi oleh IAM.

Untuk informasi selengkapnya tentang peran dan izin, lihat Memahami peran dalam dokumentasi IAM serta Peran dan izin IAM BigQuery.

Menggunakan tabel yang dikelompokkan

Mendapatkan informasi tentang tabel yang dikelompokkan

Anda bisa mendapatkan informasi tentang tabel dengan cara berikut:

• Menggunakan Konsol Google Cloud.
• Menggunakan perintah bq show alat command line bq.
• Memanggil metode API tables.get.
• Membuat kueri tabel virtual INFORMATION_SCHEMA.

Izin yang diperlukan

Setidaknya, untuk mendapatkan informasi tentang tabel, Anda harus diberi izin bigquery.tables.get. Peran IAM bawaan berikut menyertakan izin bigquery.tables.get:

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

Selain itu, jika pengguna memiliki izin bigquery.datasets.create, saat pengguna tersebut membuat set data, ia diberi akses bigquery.dataOwner. Akses bigquery.dataOwner memberi pengguna kemampuan untuk mendapatkan informasi tentang tabel dalam set data.

Untuk informasi selengkapnya tentang peran dan izin IAM di BigQuery, baca Peran dan izin bawaan.

Mendapatkan informasi tabel yang dikelompokkan

Untuk melihat informasi tentang tabel yang dikelompokkan:

Konsol

1. Di Konsol Google Cloud, buka panel Resources. Klik nama set data Anda untuk meluaskannya, lalu klik nama tabel yang ingin Anda lihat.

2. Klik Details. Halaman ini menampilkan detail tabel termasuk kolom pengelompokan.

   

SQL

Untuk tabel yang dikelompokkan, Anda dapat membuat kueri kolom CLUSTERING_ORDINAL_POSITION di tabel virtual INFORMATION_SCHEMA.COLUMNS untuk menemukan offset diindeks 1 pada kolom dalam pengelompokan kolom tabel:

1. Di Konsol Google Cloud, buka halaman BigQuery.

   Buka BigQuery

2. Di editor kueri, masukkan pernyataan berikut:

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

3. Klik Run.

Untuk informasi selengkapnya tentang cara menjalankan kueri, lihat Menjalankan kueri interaktif.

Posisi ordinal pengelompokan adalah 1 untuk column1 dan 2 untuk column2. Metadata tabel lainnya tersedia melalui tabel virtual TABLES, TABLE_OPTIONS, COLUMNS, dan COLUMN_FIELD_PATH di INFORMATION_SCHEMA.

bq

Berikan perintah bq show untuk menampilkan semua informasi tabel. Gunakan flag --schema untuk hanya menampilkan informasi skema tabel. Flag --format dapat digunakan untuk mengontrol output.

Jika Anda mendapatkan informasi tentang tabel dalam project selain project default Anda, tambahkan project ID ke set data dalam format berikut: project_id:dataset.

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

Ganti yang berikut ini:

• PROJECT_ID: project ID Anda
• DATASET: nama set data
• TABLE: nama tabel

Contoh:

Masukkan perintah berikut untuk menampilkan semua informasi tentang myclusteredtable di mydataset. mydataset di project default Anda.

bq show --format=prettyjson mydataset.myclusteredtable

Output akan terlihat seperti contoh:

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

API

Panggil metode bigquery.tables.get dan berikan parameter yang relevan.

Mencantumkan tabel yang dikelompokkan dalam set data

Anda dapat membuat daftar tabel yang dikelompokkan dalam set data dengan cara berikut:

• Menggunakan Konsol Google Cloud.
• Menggunakan perintah bq ls alat command line bq.
• Memanggil metode API tables.list.
• Menggunakan library klien.
• Membuat kueri kolom CLUSTERING_ORDINAL_POSITION dalam tabel virtual INFORMATION_SCHEMA.COLUMNS.

Izin yang diperlukan untuk mencantumkan tabel yang dikelompokkan dan langkah-langkah untuk mencantumkannya sama seperti tabel standar. Untuk informasi selengkapnya tentang mencantumkan tabel, baca Mencantumkan tabel dalam set data.

Mengubah spesifikasi pengelompokan

Anda dapat mengubah atau menghapus spesifikasi pengelompokan tabel, atau mengubah kumpulan kolom yang dikelompokkan dalam tabel yang dikelompokkan. Metode memperbarui kumpulan kolom pengelompokan ini berguna untuk tabel yang menggunakan streaming insert berkelanjutan karena tabel tersebut tidak dapat ditukar dengan mudah dengan metode lain.

Ikuti langkah-langkah berikut untuk menerapkan spesifikasi pengelompokan baru ke tabel yang tidak berpartisi atau berpartisi.

1. Pada alat bq, perbarui spesifikasi pengelompokan tabel agar sesuai dengan pengelompokan baru:

    bq update --clustering_fields=CLUSTER_COLUMN DATASET.ORIGINAL_TABLE 

   Ganti yang berikut ini:

   • CLUSTER_COLUMN: kolom tempat Anda melakukan pengelompokan—misalnya, mycolumn
   • DATASET: nama set data yang berisi tabel—misalnya, mydataset
   • ORIGINAL_TABLE: nama tabel asli—misalnya, mytable

   Anda juga dapat memanggil metode API tables.update atau tables.patch untuk mengubah spesifikasi pengelompokan.

2. Untuk mengelompokkan semua baris sesuai dengan spesifikasi pengelompokan baru, jalankan pernyataan UPDATE berikut:

   UPDATE DATASET.ORIGINAL_TABLE SET CLUSTER_COLUMN=CLUSTER_COLUMN WHERE true

   Catatan: Jika spesifikasi pengelompokan baru diterapkan ke tabel yang berada dalam penyimpanan jangka panjang, tabel tersebut akan kembali ke harga penyimpanan aktif. Untuk informasi selengkapnya, lihat Harga penyimpanan.

Keamanan tabel

Untuk mengontrol akses ke tabel di BigQuery, lihat Pengantar kontrol akses tabel.

Langkah selanjutnya

• Untuk informasi tentang cara membuat kueri tabel yang dikelompokkan, lihat Membuat kueri tabel yang dikelompokkan.
• Untuk ringkasan dukungan tabel berpartisi di BigQuery, lihat Pengantar tabel berpartisi.
• Untuk mempelajari cara membuat tabel berpartisi, lihat Membuat tabel berpartisi.
• Untuk melihat ringkasan INFORMATION_SCHEMA, buka Pengantar BigQuery INFORMATION_SCHEMA.