Mengubah skema tabel

Dokumen ini menjelaskan cara memodifikasi definisi skema untuk tabel BigQuery yang sudah ada.

Anda dapat membuat sebagian besar modifikasi skema yang dijelaskan dalam dokumen ini menggunakan pernyataan bahasa definisi data (DDL) SQL. Pernyataan ini tidak dikenai biaya.

Anda dapat memodifikasi skema tabel dengan semua cara yang dijelaskan di halaman ini, yaitu mengekspor data tabel Anda ke Cloud Storage, lalu memuat data ke dalam tabel baru dengan definisi skema yang telah dimodifikasi. Tugas pemuatan dan ekspor BigQuery tidak dikenai biaya, tetapi Anda akan dikenai biaya untuk penyimpanan data yang diekspor di Cloud Storage. Bagian berikut menjelaskan cara lain untuk melakukan berbagai jenis modifikasi skema.

Catatan: Saat skema diperbarui, perubahannya mungkin tidak segera dicerminkan dalam penayangan INFORMATION_SCHEMA.TABLES dan INFORMATION_SCHEMA.COLUMNS. Untuk melihat langsung perubahan skema, panggil metode tables.get.

Menambahkan kolom

Anda dapat menambahkan kolom ke definisi skema tabel yang sudah ada menggunakan salah satu opsi berikut:

• Menambahkan kolom kosong baru.
• Menimpa tabel dengan tugas pemuatan atau kueri.
• Menambahkan data ke tabel dengan tugas pemuatan atau kueri.

Setiap kolom yang Anda tambahkan harus mematuhi aturan BigQuery untuk nama kolom. Untuk informasi selengkapnya tentang membuat komponen skema, lihat Menentukan skema.

Menambahkan kolom kosong

Jika Anda menambahkan kolom baru ke skema tabel yang sudah ada, kolom tersebut harus berupa NULLABLE atau REPEATED. Anda tidak dapat menambahkan kolom REQUIRED ke skema tabel yang sudah ada. Menambahkan kolom REQUIRED ke skema tabel yang sudah ada di API atau alat command line bq akan menyebabkan error. Namun, Anda dapat membuat kolom REQUIRED bertingkat sebagai bagian dari kolom RECORD baru. Kolom REQUIRED hanya dapat ditambahkan ketika Anda membuat tabel saat memuat data, atau saat membuat tabel kosong dengan definisi skema.

Untuk menambahkan kolom kosong ke definisi skema tabel:

Konsol

1. Di konsol Google Cloud, buka halaman BigQuery.

   Buka BigQuery

2. Di panel Explorer, luaskan project dan set data Anda, lalu pilih tabel.

3. Di panel detail, klik tab Schema.

4. Klik Edit schema. Anda mungkin perlu men-scroll untuk melihat tombol ini.

5. Di halaman Current schema, di bagian New fields, klik Add fields.

   • Untuk Name, ketik nama kolom.
   • Untuk Type, pilih data type.
   • Untuk Mode, pilih NULLABLE atau REPEATED.

6. Setelah selesai menambahkan kolom, klik Save.

Catatan: Anda tidak dapat menggunakan konsol Google Cloud untuk menambahkan kolom ke tabel eksternal.

SQL

Gunakan pernyataan DDL ALTER TABLE ADD COLUMN:

1. Di konsol Google Cloud, buka halaman BigQuery.

   Buka BigQuery

2. Di editor kueri, masukkan pernyataan berikut:

   ALTER TABLE mydataset.mytable
   ADD COLUMN new_column STRING;

3. Klik Run.

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

Catatan: Anda tidak bisa menggunakan pernyataan ALTER TABLE ADD COLUMN untuk menambahkan kolom ke tabel eksternal.

bq

Berikan perintah bq update dan berikan file skema JSON. Jika tabel yang sedang Anda perbarui tidak berada dalam project default, tambahkan project ID ke nama set data dalam format berikut: PROJECT_ID:DATASET.

bq update PROJECT_ID:DATASET.TABLE SCHEMA

Ganti kode berikut:

• PROJECT_ID: project ID Anda.
• DATASET: nama set data yang berisi tabel yang Anda perbarui.
• TABLE: nama tabel yang Anda perbarui.
• SCHEMA: jalur ke file skema JSON di mesin lokal Anda.

Saat menentukan skema inline, Anda tidak dapat menentukan deskripsi kolom, mode, dan jenis RECORD (STRUCT). Semua mode kolom ditetapkan secara default ke NULLABLE. Akibatnya, jika Anda menambahkan kolom bertingkat baru ke RECORD, Anda harus menyediakan file skema JSON.

Jika mencoba menambahkan kolom menggunakan definisi skema inline, Anda harus menyediakan seluruh definisi skema termasuk kolom baru. Karena Anda tidak dapat menentukan mode kolom menggunakan definisi skema inline, pembaruan akan mengubah kolom REPEATED yang sudah ada menjadi NULLABLE, yang menghasilkan error berikut: BigQuery error in update operation: Provided Schema does not match Table PROJECT_ID:dataset.table. Field field has changed mode from REPEATED to NULLABLE.

Metode yang lebih baik untuk menambahkan kolom ke tabel yang sudah ada menggunakan alat command line bq adalah menyediakan file skema JSON.

Untuk menambahkan kolom kosong ke skema tabel menggunakan file skema JSON:

1. Pertama, berikan perintah bq show dengan flag --schema dan tulis skema tabel yang sudah ada ke file. Jika tabel yang sedang Anda perbarui tidak berada dalam project default, tambahkan project ID ke nama set data dalam format berikut: PROJECT_ID:DATASET.

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

   Ganti kode berikut:

   • PROJECT_ID: project ID Anda.
   • DATASET: nama set data yang berisi tabel yang Anda perbarui.
   • TABLE: nama tabel yang Anda perbarui.
   • SCHEMA: file definisi skema yang ditulis ke mesin lokal Anda.

   Misalnya, untuk menulis definisi skema mydataset.mytable ke file, masukkan perintah berikut. mydataset.mytable ada dalam project default Anda.

      bq show \
      --schema \
      --format=prettyjson \
      mydataset.mytable > /tmp/myschema.json
   

2. Buka file skema di editor teks. Skema akan terlihat seperti berikut:

   [
     {
       "mode": "REQUIRED",
       "name": "column1",
       "type": "STRING"
     },
     {
       "mode": "REQUIRED",
       "name": "column2",
       "type": "FLOAT"
     },
     {
       "mode": "REPEATED",
       "name": "column3",
       "type": "STRING"
     }
   ]
   

3. Tambahkan kolom baru di bagian akhir definisi skema. Jika Anda mencoba menambahkan kolom baru di tempat lain dalam array, error berikut akan ditampilkan: BigQuery error in update operation: Precondition Failed.

   Dengan file JSON, Anda dapat menentukan deskripsi, mode NULLABLE atau REPEATED, dan jenis RECORD untuk kolom baru. Misalnya, menggunakan definisi skema dari langkah sebelumnya, array JSON baru Anda akan terlihat seperti berikut. Dalam contoh ini, kolom NULLABLE baru bernama column4 ditambahkan. column4 menyertakan deskripsi.

     [
       {
         "mode": "REQUIRED",
         "name": "column1",
         "type": "STRING"
       },
       {
         "mode": "REQUIRED",
         "name": "column2",
         "type": "FLOAT"
       },
       {
         "mode": "REPEATED",
         "name": "column3",
         "type": "STRING"
       },
       {
         "description": "my new column",
         "mode": "NULLABLE",
         "name": "column4",
         "type": "STRING"
       }
     ]
     

   Untuk informasi selengkapnya tentang cara bekerja dengan file skema JSON, lihat Menentukan file skema JSON.

4. Setelah mengupdate file skema, berikan perintah berikut untuk mengupdate skema tabel. Jika tabel yang sedang Anda perbarui tidak berada dalam project default, tambahkan project ID ke nama set data dalam format berikut: PROJECT_ID:DATASET.

   bq update PROJECT_ID:DATASET.TABLE SCHEMA

   Ganti kode berikut:

   • PROJECT_ID: project ID Anda.
   • DATASET: nama set data yang berisi tabel yang Anda perbarui.
   • TABLE: nama tabel yang Anda perbarui.
   • SCHEMA: file definisi skema yang ditulis ke mesin lokal Anda.

   Misalnya, masukkan perintah berikut untuk memperbarui definisi skema mydataset.mytable dalam project default Anda. Jalur ke file skema di mesin lokal Anda adalah /tmp/myschema.json.

   bq update mydataset.mytable /tmp/myschema.json
   

API

Panggil metode tables.patch dan gunakan properti schema untuk menambahkan kolom kosong ke definisi skema Anda. Karena metode tables.update menggantikan seluruh resource tabel, metode tables.patch lebih disarankan.

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

// updateTableAddColumn demonstrates modifying the schema of a table to append an additional column.
func updateTableAddColumn(projectID, datasetID, tableID 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()

	tableRef := client.Dataset(datasetID).Table(tableID)
	meta, err := tableRef.Metadata(ctx)
	if err != nil {
		return err
	}
	newSchema := append(meta.Schema,
		&bigquery.FieldSchema{Name: "phone", Type: bigquery.StringFieldType},
	)
	update := bigquery.TableMetadataToUpdate{
		Schema: newSchema,
	}
	if _, err := tableRef.Update(ctx, update, meta.ETag); 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.Field;
import com.google.cloud.bigquery.FieldList;
import com.google.cloud.bigquery.LegacySQLTypeName;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardTableDefinition;
import com.google.cloud.bigquery.Table;
import java.util.ArrayList;
import java.util.List;

public class AddEmptyColumn {

  public static void runAddEmptyColumn() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableId = "MY_TABLE_NAME";
    String newColumnName = "NEW_COLUMN_NAME";
    addEmptyColumn(newColumnName, datasetName, tableId);
  }

  public static void addEmptyColumn(String newColumnName, String datasetName, String tableId) {
    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();

      Table table = bigquery.getTable(datasetName, tableId);
      Schema schema = table.getDefinition().getSchema();
      FieldList fields = schema.getFields();

      // Create the new field/column
      Field newField = Field.of(newColumnName, LegacySQLTypeName.STRING);

      // Create a new schema adding the current fields, plus the new one
      List<Field> fieldList = new ArrayList<Field>();
      fields.forEach(fieldList::add);
      fieldList.add(newField);
      Schema newSchema = Schema.of(fieldList);

      // Update the table with the new schema
      Table updatedTable =
          table.toBuilder().setDefinition(StandardTableDefinition.of(newSchema)).build();
      updatedTable.update();
      System.out.println("Empty column successfully added to table");
    } catch (BigQueryException e) {
      System.out.println("Empty column was not added. \n" + e.toString());
    }
  }
}

Node.js

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

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

// Import the Google Cloud client library and create a client
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function addEmptyColumn() {
  // Adds an empty column to the schema.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';
  const column = {name: 'size', type: 'STRING'};

  // Retrieve current table metadata
  const table = bigquery.dataset(datasetId).table(tableId);
  const [metadata] = await table.getMetadata();

  // Update table schema
  const schema = metadata.schema;
  const new_schema = schema;
  new_schema.fields.push(column);
  metadata.schema = new_schema;

  const [result] = await table.setMetadata(metadata);
  console.log(result.schema.fields);
}

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.

Tambahkan objek SchemaField baru ke salinan Table.schema, lalu ganti nilai properti Table.schema dengan skema yang diperbarui.

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 add an empty column.
# table_id = "your-project.your_dataset.your_table_name"

table = client.get_table(table_id)  # Make an API request.

original_schema = table.schema
new_schema = original_schema[:]  # Creates a copy of the schema.
new_schema.append(bigquery.SchemaField("phone", "STRING"))

table.schema = new_schema
table = client.update_table(table, ["schema"])  # Make an API request.

if len(table.schema) == len(original_schema) + 1 == len(new_schema):
    print("A new column has been added.")
else:
    print("The column has not been added.")

Menambahkan kolom bertingkat ke kolom RECORD

Selain menambahkan kolom baru ke skema tabel, Anda juga dapat menambahkan kolom bertingkat baru ke kolom RECORD. Proses penambahan kolom bertingkat baru serupa dengan proses penambahan kolom baru.

Konsol

Menambahkan kolom bertingkat baru ke kolom RECORD yang sudah ada tidak didukung oleh konsol Google Cloud.

SQL

Menambahkan kolom bertingkat baru ke kolom RECORD yang sudah ada menggunakan pernyataan DDL SQL tidak didukung.

bq

Berikan perintah bq update dan berikan file skema JSON yang menambahkan kolom bertingkat ke definisi skema kolom RECORD yang sudah ada. Jika tabel yang sedang Anda perbarui tidak berada dalam project default, tambahkan project ID ke nama set data dalam format berikut: PROJECT_ID:DATASET.

bq update PROJECT_ID:DATASET.TABLE SCHEMA

Ganti kode berikut:

• PROJECT_ID: project ID Anda.
• DATASET: nama set data yang berisi tabel yang Anda perbarui.
• TABLE: nama tabel yang Anda perbarui.
• SCHEMA: jalur ke file skema JSON di komputer mesin Anda.

Saat menentukan skema inline, Anda tidak dapat menentukan deskripsi kolom, mode, dan jenis RECORD (STRUCT). Semua mode kolom ditetapkan secara default ke NULLABLE. Akibatnya, jika Anda menambahkan kolom bertingkat baru ke RECORD, Anda harus menyediakan file skema JSON.

Untuk menambahkan kolom bertingkat ke RECORD menggunakan file skema JSON:

1. Pertama, berikan perintah bq show dengan flag --schema dan tulis skema tabel yang sudah ada ke file. Jika tabel yang sedang Anda perbarui tidak berada dalam project default Anda, tambahkan project ID ke nama set data dalam format berikut: PROJECT_ID:DATASET.TABLE.

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

   Ganti kode berikut:

   • PROJECT_ID: project ID Anda.
   • DATASET: nama set data yang berisi tabel yang Anda perbarui.
   • TABLE: nama tabel yang Anda perbarui.
   • SCHEMA: file definisi skema yang ditulis ke mesin lokal Anda.

   Misalnya, untuk menulis definisi skema mydataset.mytable ke file, masukkan perintah berikut. mydataset.mytable ada dalam project default Anda.

   bq show \
   --schema \
   --format=prettyjson \
   mydataset.mytable > /tmp/myschema.json
   

2. Buka file skema di editor teks. Skema akan terlihat seperti berikut. Dalam contoh ini, column3 adalah kolom berulang bertingkat. Kolom bertingkat adalah nested1 dan nested2. Array fields mencantumkan kolom bertingkat dalam column3.

   [
     {
       "mode": "REQUIRED",
       "name": "column1",
       "type": "STRING"
     },
     {
       "mode": "REQUIRED",
       "name": "column2",
       "type": "FLOAT"
     },
     {
       "fields": [
         {
           "mode": "NULLABLE",
           "name": "nested1",
           "type": "STRING"
         },
         {
           "mode": "NULLABLE",
           "name": "nested2",
           "type": "STRING"
         }
       ],
       "mode": "REPEATED",
       "name": "column3",
       "type": "RECORD"
     }
   ]
   

3. Tambahkan kolom bertingkat baru ke akhir array fields. Dalam contoh ini, nested3 adalah kolom bertingkat baru.

     [
       {
         "mode": "REQUIRED",
         "name": "column1",
         "type": "STRING"
       },
       {
         "mode": "REQUIRED",
         "name": "column2",
         "type": "FLOAT"
       },
       {
         "fields": [
           {
             "mode": "NULLABLE",
             "name": "nested1",
             "type": "STRING"
           },
           {
             "mode": "NULLABLE",
             "name": "nested2",
             "type": "STRING"
           },
           {
             "mode": "NULLABLE",
             "name": "nested3",
             "type": "STRING"
           }
         ],
         "mode": "REPEATED",
         "name": "column3",
         "type": "RECORD"
       }
     ]
     

   Untuk informasi selengkapnya tentang cara bekerja dengan file skema JSON, lihat Menentukan file skema JSON.

4. Setelah mengupdate file skema, berikan perintah berikut untuk mengupdate skema tabel. Jika tabel yang sedang Anda perbarui tidak berada dalam project default, tambahkan project ID ke nama set data dalam format berikut: PROJECT_ID:DATASET.

   bq update PROJECT_ID:DATASET.TABLE SCHEMA

   Ganti kode berikut:

   • PROJECT_ID: project ID Anda.
   • DATASET: nama set data yang berisi tabel yang Anda perbarui.
   • TABLE: nama tabel yang Anda perbarui.
   • SCHEMA: jalur ke file skema JSON di mesin lokal Anda.

   Misalnya, masukkan perintah berikut untuk memperbarui definisi skema mydataset.mytable dalam project default Anda. Jalur ke file skema di mesin lokal Anda adalah /tmp/myschema.json.

   bq update mydataset.mytable /tmp/myschema.json
   

API

Panggil metode tables.patch dan gunakan properti schema untuk menambahkan kolom bertingkat ke definisi skema Anda. Karena metode tables.update menggantikan seluruh resource tabel, metode tables.patch lebih disarankan.

Menambahkan kolom saat Anda menimpa atau menambahkan data

Anda dapat menambahkan kolom baru ke tabel yang sudah ada saat memuat data ke dalam tabel dan memilih untuk menimpa tabel yang sudah ada. Saat Anda menimpa tabel yang sudah ada, skema data yang sedang dimuat akan digunakan untuk menimpa skema tabel yang sudah ada. Untuk informasi tentang menimpa tabel menggunakan tugas pemuatan, lihat dokumen untuk format data Anda:

• Avro
• Parquet
• ORC
• CSV
• JSON

Menambahkan kolom dalam tugas penambahan muatan

Anda dapat menambahkan kolom ke tabel saat menambahkan data ke tabel dalam tugas pemuatan. Skema baru ditentukan oleh salah satu hal berikut:

• Deteksi otomatis (untuk file CSV dan JSON)
• Skema yang ditentukan dalam file skema JSON (untuk file CSV dan JSON)
• Data sumber yang mendeskripsikan sendiri untuk file ekspor Avro, ORC, Parquet, dan Datastore

Jika Anda menetapkan skema dalam file JSON, kolom baru harus ditetapkan di dalamnya. Jika definisi kolom baru tidak ada, error akan ditampilkan saat Anda mencoba menambahkan data.

Jika Anda menambahkan kolom baru selama operasi penambahan, nilai dalam kolom baru akan ditetapkan ke NULL untuk baris yang sudah ada.

Untuk menambahkan kolom baru saat menambahkan data ke tabel selama tugas pemuatan, gunakan salah satu opsi berikut:

bq

Gunakan perintah bq load untuk memuat data dan menentukan flag --noreplace untuk menunjukkan bahwa Anda menambahkan data ke tabel yang ada.

Jika data yang Anda tambahkan memiliki format CSV atau JSON yang dipisahkan newline, tentukan flag --autodetect untuk menggunakan deteksi otomatis skema atau berikan skema dalam file skema JSON. Kolom yang ditambahkan dapat diinferensi secara otomatis dari file ekspor Avro atau Datastore.

Tetapkan flag --schema_update_option ke ALLOW_FIELD_ADDITION untuk menunjukkan bahwa data yang Anda tambahkan berisi kolom baru.

Jika tabel yang Anda tambahkan tidak berada dalam set data project default, tambahkan project ID ke nama set data dalam format berikut: PROJECT_ID:DATASET.

(Opsional) Berikan flag --location dan tetapkan nilainya ke lokasi Anda.

Masukkan perintah load seperti berikut:

bq --location=LOCATION load \
--noreplace \
--autodetect \
--schema_update_option=ALLOW_FIELD_ADDITION \
--source_format=FORMAT \
PROJECT_ID:DATASET.TABLE \
PATH_TO_SOURCE \
SCHEMA

Ganti kode berikut:

• LOCATION: nama lokasi Anda. Flag --location bersifat opsional. Misalnya, jika Anda menggunakan BigQuery di region Tokyo, tetapkan nilai flag ke asia-northeast1. Anda dapat menetapkan nilai default untuk lokasi menggunakan file .bigqueryrc.
• FORMAT: format skema. NEWLINE_DELIMITED_JSON, CSV, AVRO, PARQUET, ORC, atau DATASTORE_BACKUP.
• PROJECT_ID: project ID Anda.
• DATASET: nama set data yang berisi tabel.
• TABLE: nama tabel yang Anda tambahkan.
• PATH_TO_SOURCE: Cloud Storage URI yang sepenuhnya memenuhi syarat, daftar URI yang dipisahkan koma, atau jalur ke file data di mesin lokal Anda.
• SCHEMA: jalur ke file skema JSON lokal. File skema diperlukan hanya untuk file CSV dan JSON jika --autodetect tidak ditentukan. Skema Avro dan Datastore diinferensi dari data sumber.

Contoh:

Masukkan perintah berikut untuk menambahkan file data Avro lokal, /tmp/mydata.avro, ke mydataset.mytable menggunakan tugas pemuatan. Karena skema dapat diinferensi secara otomatis dari data Avro, Anda tidak perlu menggunakan flag --autodetect. mydataset ada dalam project default Anda.

bq load \
--noreplace \
--schema_update_option=ALLOW_FIELD_ADDITION \
--source_format=AVRO \
mydataset.mytable \
/tmp/mydata.avro

Masukkan perintah berikut untuk menambahkan file data JSON yang dipisahkan newline di Cloud Storage ke mydataset.mytable menggunakan tugas pemuatan. Flag --autodetect digunakan untuk mendeteksi kolom baru. mydataset ada dalam project default Anda.

bq load \
--noreplace \
--autodetect \
--schema_update_option=ALLOW_FIELD_ADDITION \
--source_format=NEWLINE_DELIMITED_JSON \
mydataset.mytable \
gs://mybucket/mydata.json

Masukkan perintah berikut untuk menambahkan file data JSON yang dipisahkan newline di Cloud Storage ke mydataset.mytable menggunakan tugas pemuatan. Skema yang berisi kolom baru ditentukan dalam file skema JSON lokal, /tmp/myschema.json. mydataset ada di myotherproject, bukan project default Anda.

bq load \
--noreplace \
--schema_update_option=ALLOW_FIELD_ADDITION \
--source_format=NEWLINE_DELIMITED_JSON \
myotherproject:mydataset.mytable \
gs://mybucket/mydata.json \
/tmp/myschema.json

API

Panggil metode jobs.insert. Konfigurasikan tugas load dan setel properti berikut:

• Mereferensikan data Anda di Cloud Storage menggunakan properti sourceUris.
• Tentukan format data dengan menyetel properti sourceFormat.
• Tentukan skema di properti schema.
• Tentukan opsi pembaruan skema menggunakan properti schemaUpdateOptions.
• Tetapkan disposisi tulis tabel tujuan ke WRITE_APPEND menggunakan properti writeDisposition.

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

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

// createTableAndWidenLoad demonstrates augmenting a table's schema to add a new column via a load job.
func createTableAndWidenLoad(projectID, datasetID, tableID, filename 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()

	sampleSchema := bigquery.Schema{
		{Name: "full_name", Type: bigquery.StringFieldType},
	}
	meta := &bigquery.TableMetadata{
		Schema: sampleSchema,
	}
	tableRef := client.Dataset(datasetID).Table(tableID)
	if err := tableRef.Create(ctx, meta); err != nil {
		return err
	}
	// Now, import data from a local file, but specify field additions are allowed.
	// Because the data has a second column (age), the schema is amended as part of
	// the load.
	f, err := os.Open(filename)
	if err != nil {
		return err
	}
	source := bigquery.NewReaderSource(f)
	source.AutoDetect = true   // Allow BigQuery to determine schema.
	source.SkipLeadingRows = 1 // CSV has a single header line.

	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(source)
	loader.SchemaUpdateOptions = []string{"ALLOW_FIELD_ADDITION"}
	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}
	if err := status.Err(); 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.Field;
import com.google.cloud.bigquery.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobId;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.JobInfo.SchemaUpdateOption;
import com.google.cloud.bigquery.JobInfo.WriteDisposition;
import com.google.cloud.bigquery.LegacySQLTypeName;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.TableId;
import com.google.common.collect.ImmutableList;
import java.util.UUID;

public class AddColumnLoadAppend {

  public static void runAddColumnLoadAppend() 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";
    addColumnLoadAppend(datasetName, tableName, sourceUri);
  }

  public static void addColumnLoadAppend(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);

      // Add a new column to a BigQuery table while appending rows via a load job.
      // 'REQUIRED' fields cannot  be added to an existing schema, so the additional column must be
      // 'NULLABLE'.
      Schema newSchema =
          Schema.of(
              Field.newBuilder("name", LegacySQLTypeName.STRING)
                  .setMode(Field.Mode.REQUIRED)
                  .build(),
              // Adding below additional column during the load job
              Field.newBuilder("post_abbr", LegacySQLTypeName.STRING)
                  .setMode(Field.Mode.NULLABLE)
                  .build());

      LoadJobConfiguration loadJobConfig =
          LoadJobConfiguration.builder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.csv())
              .setWriteDisposition(WriteDisposition.WRITE_APPEND)
              .setSchema(newSchema)
              .setSchemaUpdateOptions(ImmutableList.of(SchemaUpdateOption.ALLOW_FIELD_ADDITION))
              .build();

      // Create a job ID so that we can safely retry.
      JobId jobId = JobId.of(UUID.randomUUID().toString());
      Job loadJob = bigquery.create(JobInfo.newBuilder(loadJobConfig).setJobId(jobId).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("Column successfully added during load append job");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

Node.js

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

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

// Import the Google Cloud client libraries
const {BigQuery} = require('@google-cloud/bigquery');

// Instantiate client
const bigquery = new BigQuery();

async function addColumnLoadAppend() {
  // Adds a new column to a BigQuery table while appending rows via a load job.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const fileName = '/path/to/file.csv';
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';

  // In this example, the existing table contains only the 'Name', 'Age',
  // & 'Weight' columns. 'REQUIRED' fields cannot  be added to an existing
  // schema, so the additional column must be 'NULLABLE'.
  const schema = 'Name:STRING, Age:INTEGER, Weight:FLOAT, IsMagic:BOOLEAN';

  // Retrieve destination table reference
  const [table] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .get();
  const destinationTableRef = table.metadata.tableReference;

  // Set load job options
  const options = {
    schema: schema,
    schemaUpdateOptions: ['ALLOW_FIELD_ADDITION'],
    writeDisposition: 'WRITE_APPEND',
    destinationTable: destinationTableRef,
  };

  // Load data from a local file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(fileName, options);

  console.log(`Job ${job.id} completed.`);
  console.log(`New Schema:`);
  console.log(job.configuration.load.schema.fields);

  // Check the job's status for errors
  const errors = job.status.errors;
  if (errors && errors.length > 0) {
    throw errors;
  }
}

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
# client = bigquery.Client()
# project = client.project
# dataset_ref = bigquery.DatasetReference(project, 'my_dataset')
# filepath = 'path/to/your_file.csv'

# Retrieves the destination table and checks the length of the schema
table_id = "my_table"
table_ref = dataset_ref.table(table_id)
table = client.get_table(table_ref)
print("Table {} contains {} columns.".format(table_id, len(table.schema)))

# Configures the load job to append the data to the destination table,
# allowing field addition
job_config = bigquery.LoadJobConfig()
job_config.write_disposition = bigquery.WriteDisposition.WRITE_APPEND
job_config.schema_update_options = [
    bigquery.SchemaUpdateOption.ALLOW_FIELD_ADDITION
]
# In this example, the existing table contains only the 'full_name' column.
# 'REQUIRED' fields cannot be added to an existing schema, so the
# additional column must be 'NULLABLE'.
job_config.schema = [
    bigquery.SchemaField("full_name", "STRING", mode="REQUIRED"),
    bigquery.SchemaField("age", "INTEGER", mode="NULLABLE"),
]
job_config.source_format = bigquery.SourceFormat.CSV
job_config.skip_leading_rows = 1

with open(filepath, "rb") as source_file:
    job = client.load_table_from_file(
        source_file,
        table_ref,
        location="US",  # Must match the destination dataset location.
        job_config=job_config,
    )  # API request

job.result()  # Waits for table load to complete.
print(
    "Loaded {} rows into {}:{}.".format(
        job.output_rows, dataset_id, table_ref.table_id
    )
)

# Checks the updated length of the schema
table = client.get_table(table)
print("Table {} now contains {} columns.".format(table_id, len(table.schema)))

Menambahkan kolom dalam tugas penambahan kueri

Anda dapat menambahkan kolom ke tabel saat menambahkan hasil kueri ke tabel tersebut.

Jika Anda menambahkan kolom menggunakan operasi penambahan dalam tugas kueri, skema hasil kueri akan digunakan untuk memperbarui skema tabel tujuan. Perhatikan bahwa Anda tidak dapat membuat kueri tabel di satu lokasi dan menulis hasilnya ke tabel di lokasi lain.

Untuk menambahkan kolom baru saat menambahkan data ke tabel selama tugas kueri, pilih salah satu opsi berikut:

bq

Gunakan perintah bq query untuk membuat kueri data dan menentukan flag --destination_table untuk menunjukkan tabel tujuan penambahan.

Untuk menentukan bahwa Anda menambahkan hasil kueri ke tabel tujuan yang sudah ada, tentukan flag --append_table.

Tetapkan flag --schema_update_option ke ALLOW_FIELD_ADDITION untuk menunjukkan bahwa hasil kueri yang Anda tambahkan berisi kolom baru.

Tentukan flag use_legacy_sql=false untuk menggunakan sintaksis GoogleSQL untuk kueri.

Jika tabel yang Anda tambahkan tidak berada dalam set data project default, tambahkan project ID ke nama set data dalam format berikut: PROJECT_ID:DATASET. Perhatikan bahwa tabel yang Anda kuerikan dan tabel tujuan harus berada di lokasi yang sama.

(Opsional) Berikan flag --location dan tetapkan nilainya ke lokasi Anda.

bq --location=LOCATION query \
--destination_table PROJECT_ID:DATASET.TABLE \
--append_table \
--schema_update_option=ALLOW_FIELD_ADDITION \
--use_legacy_sql=false \
'QUERY'

Ganti kode berikut:

• LOCATION: nama lokasi Anda. Flag --location bersifat opsional. Misalnya, jika Anda menggunakan BigQuery di region Tokyo, tetapkan nilai flag ke asia-northeast1. Anda dapat menetapkan nilai default untuk lokasi menggunakan file .bigqueryrc. Perhatikan bahwa Anda tidak dapat menambahkan hasil kueri ke tabel di lokasi lain.
• PROJECT_ID: project ID Anda.
• dataset: nama set data yang berisi tabel tujuan penambahan.
• TABLE: nama tabel yang Anda tambahkan.
• QUERY: kueri dalam sintaksis GoogleSQL.

Contoh:

Masukkan perintah berikut untuk membuat kueri mydataset.mytable di project default Anda dan menambahkan hasil kueri ke mydataset.mytable2 (juga di project default Anda).

bq query \
--destination_table mydataset.mytable2 \
--append_table \
--schema_update_option=ALLOW_FIELD_ADDITION \
--use_legacy_sql=false \
'SELECT
   column1,column2
 FROM
   mydataset.mytable'

Masukkan perintah berikut untuk membuat kueri mydataset.mytable di project default Anda dan untuk menambahkan hasil kueri ke mydataset.mytable2 di myotherproject.

bq query \
--destination_table myotherproject:mydataset.mytable2 \
--append_table \
--schema_update_option=ALLOW_FIELD_ADDITION \
--use_legacy_sql=false \
'SELECT
   column1,column2
 FROM
   mydataset.mytable'

API

Panggil metode jobs.insert. Konfigurasikan tugas query dan setel properti berikut:

• Tentukan tabel tujuan menggunakan properti destinationTable.
• Tetapkan disposisi tulis tabel tujuan ke WRITE_APPEND menggunakan properti writeDisposition.
• Tentukan opsi pembaruan skema menggunakan properti schemaUpdateOptions.
• Tentukan kueri GoogleSQL menggunakan properti query.

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

// createTableAndWidenQuery demonstrates how the schema of a table can be modified to add columns by appending
// query results that include the new columns.
func createTableAndWidenQuery(projectID, datasetID, tableID 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()

	// First, we create a sample table.
	sampleSchema := bigquery.Schema{
		{Name: "full_name", Type: bigquery.StringFieldType, Required: true},
		{Name: "age", Type: bigquery.IntegerFieldType, Required: true},
	}
	original := &bigquery.TableMetadata{
		Schema: sampleSchema,
	}
	tableRef := client.Dataset(datasetID).Table(tableID)
	if err := tableRef.Create(ctx, original); err != nil {
		return err
	}
	// Our table has two columns.  We'll introduce a new favorite_color column via
	// a subsequent query that appends to the table.
	q := client.Query("SELECT \"Timmy\" as full_name, 85 as age, \"Blue\" as favorite_color")
	q.SchemaUpdateOptions = []string{"ALLOW_FIELD_ADDITION"}
	q.QueryConfig.Dst = client.Dataset(datasetID).Table(tableID)
	q.WriteDisposition = bigquery.WriteAppend
	q.Location = "US"
	job, err := q.Run(ctx)
	if err != nil {
		return err
	}
	_, err = job.Wait(ctx)
	if 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.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.JobInfo.SchemaUpdateOption;
import com.google.cloud.bigquery.JobInfo.WriteDisposition;
import com.google.cloud.bigquery.QueryJobConfiguration;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableResult;
import com.google.common.collect.ImmutableList;

public class RelaxTableQuery {

  public static void runRelaxTableQuery() throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    relaxTableQuery(projectId, datasetName, tableName);
  }

  // To relax all columns in a destination table when you append data to it during a query job
  public static void relaxTableQuery(String projectId, String datasetName, String tableName)
      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);

      String sourceTable = "`" + projectId + "." + datasetName + "." + tableName + "`";
      String query = "SELECT word FROM " + sourceTable + " WHERE word like '%is%'";

      QueryJobConfiguration queryConfig =
          QueryJobConfiguration.newBuilder(query)
              // Use standard SQL syntax for queries.
              // See: https://cloud.google.com/bigquery/sql-reference/
              .setUseLegacySql(false)
              .setSchemaUpdateOptions(ImmutableList.of(SchemaUpdateOption.ALLOW_FIELD_RELAXATION))
              .setWriteDisposition(WriteDisposition.WRITE_APPEND)
              .setDestinationTable(tableId)
              .build();

      Job queryJob = bigquery.create(JobInfo.newBuilder(queryConfig).build());

      queryJob = queryJob.waitFor();

      // Check for errors
      if (queryJob == null) {
        throw new Exception("Job no longer exists");
      } else if (queryJob.getStatus().getError() != null) {
        // You can also look at queryJob.getStatus().getExecutionErrors() for all
        // errors, not just the latest one.
        throw new Exception(queryJob.getStatus().getError().toString());
      }

      // Get the results.
      TableResult results = queryJob.getQueryResults();

      // Print all pages of the results.
      results
          .iterateAll()
          .forEach(
              rows -> {
                rows.forEach(row -> System.out.println("row: " + row.toString()));
              });

      System.out.println("Successfully relaxed all columns in destination table during query job");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Columns not relaxed during query job \n" + e.toString());
    }
  }
}

Node.js

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

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

// Import the Google Cloud client libraries
const {BigQuery} = require('@google-cloud/bigquery');

// Instantiate client
const bigquery = new BigQuery();

async function addColumnQueryAppend() {
  // Adds a new column to a BigQuery table while appending rows via a query job.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';

  // Retrieve destination table reference
  const [table] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .get();
  const destinationTableRef = table.metadata.tableReference;

  // In this example, the existing table contains only the 'name' column.
  // 'REQUIRED' fields cannot  be added to an existing schema,
  // so the additional column must be 'NULLABLE'.
  const query = `SELECT name, year
    FROM \`bigquery-public-data.usa_names.usa_1910_2013\`
    WHERE state = 'TX'
    LIMIT 10`;

  // Set load job options
  const options = {
    query: query,
    schemaUpdateOptions: ['ALLOW_FIELD_ADDITION'],
    writeDisposition: 'WRITE_APPEND',
    destinationTable: destinationTableRef,
    // Location must match that of the dataset(s) referenced in the query.
    location: 'US',
  };

  const [job] = await bigquery.createQueryJob(options);
  console.log(`Job ${job.id} started.`);

  // Wait for the query to finish
  const [rows] = await job.getQueryResults();
  console.log(`Job ${job.id} completed.`);

  // Print the results
  console.log('Rows:');
  rows.forEach(row => console.log(row));
}

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 destination table.
# table_id = "your-project.your_dataset.your_table_name"

# Retrieves the destination table and checks the length of the schema.
table = client.get_table(table_id)  # Make an API request.
print("Table {} contains {} columns".format(table_id, len(table.schema)))

# Configures the query to append the results to a destination table,
# allowing field addition.
job_config = bigquery.QueryJobConfig(
    destination=table_id,
    schema_update_options=[bigquery.SchemaUpdateOption.ALLOW_FIELD_ADDITION],
    write_disposition=bigquery.WriteDisposition.WRITE_APPEND,
)

# Start the query, passing in the extra configuration.
query_job = client.query(
    # In this example, the existing table contains only the 'full_name' and
    # 'age' columns, while the results of this query will contain an
    # additional 'favorite_color' column.
    'SELECT "Timmy" as full_name, 85 as age, "Blue" as favorite_color;',
    job_config=job_config,
)  # Make an API request.
query_job.result()  # Wait for the job to complete.

# Checks the updated length of the schema.
table = client.get_table(table_id)  # Make an API request.
print("Table {} now contains {} columns".format(table_id, len(table.schema)))

Mengubah nama kolom

Untuk mengganti nama kolom pada tabel, gunakan pernyataan DDL ALTER TABLE RENAME COLUMN. Contoh berikut mengganti nama kolom old_name menjadi new_name di mytable:

ALTER TABLE mydataset.mytable
  RENAME COLUMN old_name TO new_name;

Untuk informasi selengkapnya tentang pernyataan ALTER TABLE RENAME COLUMN, lihat Detail DDL.

Mengubah jenis data kolom

Mengubah jenis data kolom tidak didukung oleh konsol Google Cloud, alat command line bq, atau BigQuery API. Error akan muncul jika Anda mencoba memperbarui tabel dengan menerapkan skema yang menentukan jenis data baru untuk kolom.

Mengubah jenis data kolom dengan pernyataan DDL

Anda dapat menggunakan GoogleSQL untuk membuat perubahan tertentu pada jenis data kolom. Untuk mengetahui informasi selengkapnya dan daftar lengkap konversi jenis data yang didukung, lihat pernyataan DDL ALTER COLUMN SET DATA TYPE.

Contoh berikut membuat tabel dengan kolom jenis INT64, lalu memperbarui jenisnya menjadi NUMERIC:

CREATE TABLE mydataset.mytable(c1 INT64);

ALTER TABLE mydataset.mytable
ALTER COLUMN c1 SET DATA TYPE NUMERIC;

Contoh berikut membuat tabel dengan kolom bertingkat dengan dua kolom, lalu memperbarui jenis salah satu kolom dari INT menjadi NUMERIC:

CREATE TABLE mydataset.mytable(s1 STRUCT<a INT64, b STRING>);

ALTER TABLE mydataset.mytable ALTER COLUMN s1
SET DATA TYPE STRUCT<a NUMERIC, b STRING>;

Mentransmisikan jenis data kolom

Untuk mengubah jenis data kolom menjadi jenis castable, gunakan kueri SQL untuk memilih data tabel, mentransmisikan kolom yang relevan, dan menimpa tabel. Transmisi dan penimpaan tidak direkomendasikan untuk tabel yang sangat besar karena memerlukan pemindaian tabel lengkap.

Contoh berikut menunjukkan kueri SQL yang memilih semua data dari column_two dan column_three di mydataset.mytable, lalu mentransmisikan column_one dari DATE ke STRING. Hasil kueri digunakan untuk menimpa tabel yang sudah ada. Tabel yang ditimpa menyimpan column_one sebagai jenis data STRING.

Saat menggunakan CAST, kueri dapat gagal jika BigQuery tidak dapat melakukan transmisi. Untuk mengetahui detail tentang aturan transmisi di GoogleSQL, lihat Melakukan transmisi.

Konsol

1. Di konsol Google Cloud, buka halaman BigQuery.

   Buka BigQuery

2. Di Query editor, masukkan kueri berikut untuk memilih semua data dari column_two dan column_three di mydataset.mytable, serta untuk mentransmisikan column_one dari DATE ke STRING. Kueri menggunakan alias untuk mentransmisikan column_one dengan nama yang sama. mydataset.mytable ada dalam project default Anda.

   SELECT
    column_two,
    column_three,
    CAST(column_one AS STRING) AS column_one
   FROM
    mydataset.mytable;

3. Klik More dan pilih Query settings.

4. Di bagian Destination, lakukan tindakan berikut:

   1. Pilih Set a destination table for query results.

   2. Untuk Project name, biarkan nilai ditetapkan ke project default Anda. Ini adalah project yang berisi mydataset.mytable.

   3. Untuk Dataset, pilih mydataset.

   4. Di kolom Table ID, masukkan mytable.

   5. Untuk Destination table write preference, pilih Overwrite table. Opsi ini menimpa mytable menggunakan hasil kueri.

5. Secara opsional, pilih lokasi data Anda.

6. Untuk memperbarui setelan, klik Save.

7. Klik Run.

   Saat tugas kueri selesai, jenis data column_one adalah STRING.

bq

Masukkan perintah bq query berikut untuk memilih semua data dari column_two dan column_three di mydataset.mytable, serta untuk mentransmisikan column_one dari DATE ke STRING. Kueri menggunakan alias untuk mentransmisikan column_one dengan nama yang sama. mydataset.mytable ada dalam project default Anda.

Hasil kueri ditulis ke mydataset.mytable menggunakan flag --destination_table, dan flag --replace digunakan untuk menimpa mytable. Tentukan flag use_legacy_sql=false untuk menggunakan sintaksis GoogleSQL.

Jika ingin, berikan flag --location dan tetapkan nilai ke lokasi Anda.

bq query \
    --destination_table mydataset.mytable \
    --replace \
    --use_legacy_sql=false \
'SELECT
  column_two,
  column_three,
  CAST(column_one AS STRING) AS column_one
FROM
  mydataset.mytable'

API

Untuk memilih semua data dari column_two dan column_three di mydataset.mytable, serta untuk mentransmisikan column_one dari DATE ke STRING, panggil metode jobs.insert dan konfigurasi tugas query. Secara opsional, tentukan lokasi Anda di properti location di bagian jobReference.

Kueri SQL yang digunakan dalam tugas kueri adalah SELECT column_two, column_three, CAST(column_one AS STRING) AS column_one FROM mydataset.mytable. Kueri menggunakan alias untuk mentransmisikan column_one dengan nama yang sama.

Untuk menimpa mytable dengan hasil kueri, sertakan mydataset.mytable di properti configuration.query.destinationTable, dan tentukan WRITE_TRUNCATE di properti configuration.query.writeDisposition.

Mengubah mode kolom

Satu-satunya modifikasi yang didukung dan dapat Anda buat untuk mode kolom adalah mengubahnya dari REQUIRED menjadi NULLABLE. Mengubah mode kolom dari REQUIRED menjadi NULLABLE juga disebut relaksasi kolom. Anda juga dapat merelaksasi kolom saat memuat data untuk menimpa tabel yang sudah ada, atau saat menambahkan data ke tabel yang sudah ada. Anda tidak dapat mengubah mode kolom dari NULLABLE menjadi REQUIRED.

Membuat kolom NULLABLE di tabel yang sudah ada

Untuk mengubah mode kolom dari REQUIRED menjadi NULLABLE, pilih salah satu opsi berikut:

Konsol

1. Buka halaman BigQuery.

   Buka BigQuery

2. Di panel Explorer, luaskan project dan set data Anda, lalu pilih tabel.

3. Di panel detail, klik tab Schema.

4. Klik Edit schema. Anda mungkin perlu men-scroll untuk melihat tombol ini.

5. Di halaman Current schema, cari kolom yang ingin Anda ubah.

6. Dalam menu drop-down Mode untuk kolom tersebut, pilih NULLABLE.

7. Untuk memperbarui setelan, klik Save.

Catatan: Anda tidak dapat menggunakan konsol Google Cloud untuk mengubah kolom dalam tabel eksternal.

SQL

Gunakan pernyataan DDL ALTER COLUMN DROP NOT NULL. Contoh berikut mengubah mode kolom mycolumn dari REQUIRED menjadi NULLABLE:

1. Di konsol Google Cloud, buka halaman BigQuery.

   Buka BigQuery

2. Di editor kueri, masukkan pernyataan berikut:

   ALTER TABLE mydataset.mytable
   ALTER COLUMN mycolumn
   DROP NOT NULL;

3. Klik Run.

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

bq

1. Pertama, berikan perintah bq show dengan flag --schema dan tulis skema tabel yang sudah ada ke file. Jika tabel yang sedang Anda perbarui tidak berada dalam project default, tambahkan project ID ke nama set data dalam format berikut: PROJECT_ID:DATASET.

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

   Ganti kode berikut:

   • PROJECT_ID: project ID Anda.
   • DATASET: nama set data yang berisi tabel yang Anda perbarui.
   • TABLE: nama tabel yang Anda perbarui.
   • SCHEMA_FILE: file definisi skema yang ditulis ke mesin lokal Anda.

   Misalnya, untuk menulis definisi skema mydataset.mytable ke file, masukkan perintah berikut. mydataset.mytable ada dalam project default Anda.

     bq show \
     --schema \
     --format=prettyjson \
     mydataset.mytable > /tmp/myschema.json
   

2. Buka file skema di editor teks. Skema akan terlihat seperti berikut:

   [
     {
       "mode": "REQUIRED",
       "name": "column1",
       "type": "STRING"
     },
     {
       "mode": "REQUIRED",
       "name": "column2",
       "type": "FLOAT"
     },
     {
       "mode": "REPEATED",
       "name": "column3",
       "type": "STRING"
     }
   ]
   

3. Ubah mode kolom yang sudah ada dari REQUIRED menjadi NULLABLE. Dalam contoh ini, mode untuk column1 dalam keadaan relaks.

   [
     {
       "mode": "NULLABLE",
       "name": "column1",
       "type": "STRING"
     },
     {
       "mode": "REQUIRED",
       "name": "column2",
       "type": "FLOAT"
     },
     {
       "mode": "REPEATED",
       "name": "column3",
       "type": "STRING"
     }
   ]
   

   Untuk informasi selengkapnya tentang cara bekerja dengan file skema JSON, lihat Menentukan file skema JSON.

4. Setelah mengupdate file skema, berikan perintah berikut untuk mengupdate skema tabel. Jika tabel yang sedang Anda perbarui tidak berada dalam project default, tambahkan project ID ke nama set data dalam format berikut: PROJECT_ID:DATASET.

   bq update PROJECT_ID:DATASET.TABLE SCHEMA

   Ganti kode berikut:

   • PROJECT_ID: project ID Anda.
   • DATASET: nama set data yang berisi tabel yang Anda perbarui.
   • TABLE: nama tabel yang Anda perbarui.
   • SCHEMA: jalur ke file skema JSON di mesin lokal Anda.

   Misalnya, masukkan perintah berikut untuk memperbarui definisi skema mydataset.mytable dalam project default Anda. Jalur ke file skema di mesin lokal Anda adalah /tmp/myschema.json.

     bq update mydataset.mytable /tmp/myschema.json
   

API

Panggil tables.patch dan gunakan properti schema untuk mengubah kolom REQUIRED menjadi NULLABLE dalam definisi skema Anda. Karena metode tables.update menggantikan seluruh resource tabel, metode tables.patch lebih disarankan.

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

// relaxTableAPI demonstrates modifying the schema of a table to remove the requirement that columns allow
// no NULL values.
func relaxTableAPI(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()

	// Setup: We first create a table with a schema that's restricts NULL values.
	sampleSchema := bigquery.Schema{
		{Name: "full_name", Type: bigquery.StringFieldType, Required: true},
		{Name: "age", Type: bigquery.IntegerFieldType, Required: true},
	}
	original := &bigquery.TableMetadata{
		Schema: sampleSchema,
	}
	if err := client.Dataset(datasetID).Table(tableID).Create(ctx, original); err != nil {
		return err
	}

	tableRef := client.Dataset(datasetID).Table(tableID)
	meta, err := tableRef.Metadata(ctx)
	if err != nil {
		return err
	}
	// Iterate through the schema to set all Required fields to false (nullable).
	var relaxed bigquery.Schema
	for _, v := range meta.Schema {
		v.Required = false
		relaxed = append(relaxed, v)
	}
	newMeta := bigquery.TableMetadataToUpdate{
		Schema: relaxed,
	}
	if _, err := tableRef.Update(ctx, newMeta, meta.ETag); 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.Field;
import com.google.cloud.bigquery.LegacySQLTypeName;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardTableDefinition;
import com.google.cloud.bigquery.Table;

public class RelaxColumnMode {

  public static void runRelaxColumnMode() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableId = "MY_TABLE_NAME";
    relaxColumnMode(datasetName, tableId);
  }

  public static void relaxColumnMode(String datasetName, String tableId) {
    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();

      Table table = bigquery.getTable(datasetName, tableId);

      // Create new relaxed schema based on the existing table schema
      Schema relaxedSchema =
          Schema.of(
              // The only supported modification you can make to a column's mode is changing it from
              // REQUIRED to NULLABLE
              // Changing a column's mode from REQUIRED to NULLABLE is also called column relaxation
              // INFO: LegacySQLTypeName will be updated to StandardSQLTypeName in release 1.103.0
              Field.newBuilder("word", LegacySQLTypeName.STRING)
                  .setMode(Field.Mode.NULLABLE)
                  .build(),
              Field.newBuilder("word_count", LegacySQLTypeName.STRING)
                  .setMode(Field.Mode.NULLABLE)
                  .build(),
              Field.newBuilder("corpus", LegacySQLTypeName.STRING)
                  .setMode(Field.Mode.NULLABLE)
                  .build(),
              Field.newBuilder("corpus_date", LegacySQLTypeName.STRING)
                  .setMode(Field.Mode.NULLABLE)
                  .build());

      // Update the table with the new schema
      Table updatedTable =
          table.toBuilder().setDefinition(StandardTableDefinition.of(relaxedSchema)).build();
      updatedTable.update();
      System.out.println("Table schema successfully relaxed.");
    } catch (BigQueryException e) {
      System.out.println("Table schema not relaxed \n" + e.toString());
    }
  }
}

Node.js

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

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

// Import the Google Cloud client library and create a client
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function relaxColumn() {
  /**
   * Changes columns from required to nullable.
   * Assumes existing table with the following schema:
   * [{name: 'Name', type: 'STRING', mode: 'REQUIRED'},
   * {name: 'Age', type: 'INTEGER'},
   * {name: 'Weight', type: 'FLOAT'},
   * {name: 'IsMagic', type: 'BOOLEAN'}];
   */

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';

  const newSchema = [
    {name: 'Name', type: 'STRING', mode: 'NULLABLE'},
    {name: 'Age', type: 'INTEGER'},
    {name: 'Weight', type: 'FLOAT'},
    {name: 'IsMagic', type: 'BOOLEAN'},
  ];

  // Retrieve current table metadata
  const table = bigquery.dataset(datasetId).table(tableId);
  const [metadata] = await table.getMetadata();

  // Update schema
  metadata.schema = newSchema;
  const [apiResponse] = await table.setMetadata(metadata);

  console.log(apiResponse.schema.fields);
}

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.

Timpa properti Table.schema dengan daftar objek SchemaField yang mode propertinya ditetapkan ke 'NULLABLE'

from google.cloud import bigquery

client = bigquery.Client()

# TODO(dev): Change table_id to full name of the table you want to create.
table_id = "your-project.your_dataset.your_table"

table = client.get_table(table_id)
new_schema = []
for field in table.schema:
    if field.mode != "REQUIRED":
        new_schema.append(field)
    else:
        # SchemaField properties cannot be edited after initialization.
        # To make changes, construct new SchemaField objects.
        new_field = field.to_api_repr()
        new_field["mode"] = "NULLABLE"
        relaxed_field = bigquery.SchemaField.from_api_repr(new_field)
        new_schema.append(relaxed_field)

table.schema = new_schema
table = client.update_table(table, ["schema"])

print(f"Updated {table_id} schema: {table.schema}.")

Membuat kolom NULLABLE dengan tugas pemuatan tambahan

Anda dapat merelaksasi mode kolom saat menambahkan data ke tabel dalam tugas pemuatan. Pilih salah satu dari opsi berikut berdasarkan jenis file:

• Saat menambahkan data dari file CSV dan JSON, relaksasikan mode untuk setiap kolom dengan menentukan file skema JSON.
• Saat menambahkan data dari file Avro, ORC, atau Parquet, relaksasikan kolom ke NULL dalam skema Anda dan biarkan inferensi skema mendeteksi kolom yang direlaksasi.

Catatan: Relaksasi kolom tidak berlaku untuk penambahan ekspor Datastore. Kolom dalam tabel yang dibuat dengan memuat file ekspor Datastore selalu NULLABLE.

Untuk merelaksasi kolom dari REQUIRED menjadi NULLABLE saat menambahkan data ke tabel selama tugas pemuatan, pilih salah satu opsi berikut:

Konsol

Anda tidak dapat merelaksasi mode kolom menggunakan konsol Google Cloud.

bq

Gunakan perintah bq load untuk memuat data dan menentukan flag --noreplace untuk menunjukkan bahwa Anda menambahkan data ke tabel yang ada.

Jika data yang Anda tambahkan memiliki format CSV atau JSON yang dipisahkan newline, tentukan kolom yang direlaksasi dalam file skema JSON lokal, atau gunakan flag --autodetect untuk menggunakan deteksi skema guna menemukan kolom yang direlaksasi dalam data sumber.

Kolom yang direlaksasi dapat diinferensikan secara otomatis dari file Avro, ORC, dan Parquet. Relaksasi kolom tidak berlaku untuk penambahan ekspor Datastore. Kolom dalam tabel yang dibuat dengan memuat file ekspor Datastore selalu NULLABLE.

Tetapkan flag --schema_update_option ke ALLOW_FIELD_RELAXATION untuk menunjukkan bahwa data yang Anda tambahkan berisi kolom yang direlaksasi.

Jika tabel yang Anda tambahkan tidak berada dalam set data project default, tambahkan project ID ke nama set data dalam format berikut: PROJECT_ID:DATASET.

(Opsional) Berikan flag --location dan tetapkan nilainya ke lokasi Anda.

Masukkan perintah load seperti berikut:

bq --location=LOCATION load \
--noreplace \
--schema_update_option=ALLOW_FIELD_RELAXATION \
--source_format=FORMAT \
PROJECT_ID:DATASET.TABLE \
PATH_TO_SOURCE \
SCHEMA

Ganti kode berikut:

• LOCATION: nama lokasi Anda. Flag --location bersifat opsional. Misalnya, jika Anda menggunakan BigQuery di region Tokyo, tetapkan nilai flag ke asia-northeast1. Anda dapat menetapkan nilai default untuk lokasi menggunakan file .bigqueryrc.
• FORMAT: NEWLINE_DELIMITED_JSON, CSV, PARQUET, ORC, atau AVRO. File DATASTORE_BACKUP tidak memerlukan relaksasi kolom. Kolom dalam tabel yang dibuat dari file ekspor Datastore selalu NULLABLE.
• PROJECT_ID: project ID Anda.
• dataset adalah nama set data yang berisi tabel.
• TABLE: nama tabel yang Anda tambahkan.
• PATH_TO_SOURCE: Cloud Storage URI yang sepenuhnya memenuhi syarat, daftar URI yang dipisahkan koma, atau jalur ke file data di mesin lokal Anda.
• SCHEMA: jalur ke file skema JSON lokal. Opsi ini hanya digunakan untuk file CSV dan JSON. Kolom yang direlaksasi disimpulkan secara otomatis dari file Avro.

Contoh:

Masukkan perintah berikut untuk menambahkan file data Avro lokal, /tmp/mydata.avro, ke mydataset.mytable menggunakan tugas pemuatan. Karena kolom yang direlaksasi dapat disimpulkan secara otomatis dari data Avro, Anda tidak perlu menentukan file skema. mydataset ada dalam project default Anda.

bq load \
    --noreplace \
    --schema_update_option=ALLOW_FIELD_RELAXATION \
    --source_format=AVRO \
    mydataset.mytable \
    /tmp/mydata.avro

Masukkan perintah berikut untuk menambahkan data dari file JSON yang dipisahkan newline di Cloud Storage ke mydataset.mytable menggunakan tugas pemuatan. Skema berisi kolom yang direlaksasi berada dalam file skema JSON lokal — /tmp/myschema.json. mydataset ada dalam project default Anda.

bq load \
--noreplace \
--schema_update_option=ALLOW_FIELD_RELAXATION \
--source_format=NEWLINE_DELIMITED_JSON \
mydataset.mytable \
gs://mybucket/mydata.json \
/tmp/myschema.json

Masukkan perintah berikut untuk menambahkan data dalam file CSV di mesin lokal Anda ke mydataset.mytable menggunakan tugas pemuatan. Perintah tersebut menggunakan deteksi otomatis skema untuk menemukan kolom yang direlaksasi dalam data sumber. mydataset berada di myotherproject, bukan di project default Anda.

bq load \
--noreplace \
--schema_update_option=ALLOW_FIELD_RELAXATION \
--source_format=CSV \
--autodetect \
myotherproject:mydataset.mytable \
mydata.csv

API

Panggil metode jobs.insert. Konfigurasikan tugas load dan setel properti berikut:

• Mereferensikan data Anda di Cloud Storage menggunakan properti sourceUris.
• Tentukan format data dengan menyetel properti sourceFormat.
• Tentukan skema di properti schema.
• Tentukan opsi pembaruan skema menggunakan properti schemaUpdateOptions.
• Tetapkan disposisi tulis tabel tujuan ke WRITE_APPEND menggunakan properti writeDisposition.

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

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

// relaxTableImport demonstrates amending the schema of a table to relax columns from
// not allowing NULL values to allowing them.
func relaxTableImport(projectID, datasetID, tableID, filename 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()

	sampleSchema := bigquery.Schema{
		{Name: "full_name", Type: bigquery.StringFieldType, Required: true},
		{Name: "age", Type: bigquery.IntegerFieldType, Required: true},
	}
	meta := &bigquery.TableMetadata{
		Schema: sampleSchema,
	}
	tableRef := client.Dataset(datasetID).Table(tableID)
	if err := tableRef.Create(ctx, meta); err != nil {
		return err
	}
	// Now, import data from a local file, but specify relaxation of required
	// fields as a side effect while the data is appended.
	f, err := os.Open(filename)
	if err != nil {
		return err
	}
	source := bigquery.NewReaderSource(f)
	source.AutoDetect = true   // Allow BigQuery to determine schema.
	source.SkipLeadingRows = 1 // CSV has a single header line.

	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(source)
	loader.SchemaUpdateOptions = []string{"ALLOW_FIELD_RELAXATION"}
	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}
	if err := status.Err(); 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.CsvOptions;
import com.google.cloud.bigquery.Field;
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.Table;
import com.google.cloud.bigquery.TableId;
import com.google.common.collect.ImmutableList;

// Sample to append relax column in a table.
public class RelaxColumnLoadAppend {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.csv";
    relaxColumnLoadAppend(datasetName, tableName, sourceUri);
  }

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

      // Retrieve destination table reference
      Table table = bigquery.getTable(TableId.of(datasetName, tableName));

      // column as a 'REQUIRED' field.
      Field name =
          Field.newBuilder("name", StandardSQLTypeName.STRING).setMode(Field.Mode.REQUIRED).build();
      Field postAbbr =
          Field.newBuilder("post_abbr", StandardSQLTypeName.STRING)
              .setMode(Field.Mode.REQUIRED)
              .build();
      Schema schema = Schema.of(name, postAbbr);

      // Skip header row in the file.
      CsvOptions csvOptions = CsvOptions.newBuilder().setSkipLeadingRows(1).build();

      // Set job options
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.newBuilder(table.getTableId(), sourceUri)
              .setSchema(schema)
              .setFormatOptions(csvOptions)
              .setSchemaUpdateOptions(
                  ImmutableList.of(JobInfo.SchemaUpdateOption.ALLOW_FIELD_RELAXATION))
              .setWriteDisposition(JobInfo.WriteDisposition.WRITE_APPEND)
              .build();

      // Create a load job and wait for it to complete.
      Job job = bigquery.create(JobInfo.of(loadConfig));
      job = job.waitFor();
      // Check the job's status for errors
      if (job.isDone() && job.getStatus().getError() == null) {
        System.out.println("Relax column append successfully loaded in a table");
      } else {
        System.out.println(
            "BigQuery was unable to load into the table due to an error:"
                + job.getStatus().getError());
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

Node.js

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

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

// Import the Google Cloud client libraries
const {BigQuery} = require('@google-cloud/bigquery');

// Instantiate client
const bigquery = new BigQuery();

async function relaxColumnLoadAppend() {
  // Changes required column to nullable in load append job.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const fileName = '/path/to/file.csv';
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';

  // In this example, the existing table contains the 'Name'
  // column as a 'REQUIRED' field.
  const schema = 'Age:INTEGER, Weight:FLOAT, IsMagic:BOOLEAN';

  // Retrieve destination table reference
  const [table] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .get();
  const destinationTableRef = table.metadata.tableReference;

  // Set load job options
  const options = {
    schema: schema,
    schemaUpdateOptions: ['ALLOW_FIELD_RELAXATION'],
    writeDisposition: 'WRITE_APPEND',
    destinationTable: destinationTableRef,
  };

  // Load data from a local file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(fileName, options);

  console.log(`Job ${job.id} completed.`);

  // Check the job's status for errors
  const errors = job.status.errors;
  if (errors && errors.length > 0) {
    throw errors;
  }
}

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
# client = bigquery.Client()
# project = client.project
# dataset_ref = bigquery.DatasetReference(project, 'my_dataset')
# filepath = 'path/to/your_file.csv'

# Retrieves the destination table and checks the number of required fields
table_id = "my_table"
table_ref = dataset_ref.table(table_id)
table = client.get_table(table_ref)
original_required_fields = sum(field.mode == "REQUIRED" for field in table.schema)
# In this example, the existing table has 3 required fields.
print("{} fields in the schema are required.".format(original_required_fields))

# Configures the load job to append the data to a destination table,
# allowing field relaxation
job_config = bigquery.LoadJobConfig()
job_config.write_disposition = bigquery.WriteDisposition.WRITE_APPEND
job_config.schema_update_options = [
    bigquery.SchemaUpdateOption.ALLOW_FIELD_RELAXATION
]
# In this example, the existing table contains three required fields
# ('full_name', 'age', and 'favorite_color'), while the data to load
# contains only the first two fields.
job_config.schema = [
    bigquery.SchemaField("full_name", "STRING", mode="REQUIRED"),
    bigquery.SchemaField("age", "INTEGER", mode="REQUIRED"),
]
job_config.source_format = bigquery.SourceFormat.CSV
job_config.skip_leading_rows = 1

with open(filepath, "rb") as source_file:
    job = client.load_table_from_file(
        source_file,
        table_ref,
        location="US",  # Must match the destination dataset location.
        job_config=job_config,
    )  # API request

job.result()  # Waits for table load to complete.
print(
    "Loaded {} rows into {}:{}.".format(
        job.output_rows, dataset_id, table_ref.table_id
    )
)

# Checks the updated number of required fields
table = client.get_table(table)
current_required_fields = sum(field.mode == "REQUIRED" for field in table.schema)
print("{} fields in the schema are now required.".format(current_required_fields))

Membuat semua kolom NULLABLE dengan tugas penambahan

Anda dapat merelaksasi semua kolom dalam tabel saat menambahkan hasil kueri ke tabel tersebut. Anda dapat merelaksasi semua kolom wajib diisi di tabel tujuan dengan menyetel flag --schema_update_option ke ALLOW_FIELD_RELAXATION. Anda tidak dapat merelaksasi kolom individual dalam tabel tujuan menggunakan penambahan kueri. Untuk merelaksasi kolom individual dengan tugas penambahan muatan, lihat Membuat kolom NULLABLE dengan tugas penambahan.

Untuk merelaksasi semua kolom saat menambahkan hasil kueri ke tabel tujuan, pilih salah satu opsi berikut:

Konsol

Anda tidak dapat merelaksasi mode kolom menggunakan konsol Google Cloud.

bq

Gunakan perintah bq query untuk membuat kueri data dan menentukan flag --destination_table untuk menunjukkan tabel tujuan penambahan.

Untuk menentukan bahwa Anda menambahkan hasil kueri ke tabel tujuan yang sudah ada, tentukan flag --append_table.

Setel flag --schema_update_option ke ALLOW_FIELD_RELAXATION untuk menunjukkan bahwa semua kolom REQUIRED dalam tabel tujuan penambahan harus diubah menjadi NULLABLE.

Tentukan flag use_legacy_sql=false untuk menggunakan sintaksis GoogleSQL untuk kueri.

Jika tabel yang Anda tambahkan tidak berada dalam set data project default, tambahkan project ID ke nama set data dalam format berikut: PROJECT_ID:DATASET.

(Opsional) Berikan flag --location dan tetapkan nilainya ke lokasi Anda.

bq --location=LOCATION query \
--destination_table PROJECT_ID:DATASET.TABLE \
--append_table \
--schema_update_option=ALLOW_FIELD_RELAXATION \
--use_legacy_sql=false \
'QUERY'

Ganti kode berikut:

• LOCATION: nama lokasi Anda. Flag --location bersifat opsional. Misalnya, jika Anda menggunakan BigQuery di region Tokyo, tetapkan nilai flag ke asia-northeast1. Anda dapat menetapkan nilai default untuk lokasi menggunakan file .bigqueryrc.
• PROJECT_ID: project ID Anda.
• DATASET: nama set data yang berisi tabel tujuan penambahan.
• TABLE: nama tabel yang Anda tambahkan.
• QUERY: kueri dalam sintaksis GoogleSQL.

Contoh:

Masukkan kueri perintah berikut mydataset.mytable dalam project default Anda untuk menambahkan hasil kueri ke mydataset.mytable2 (juga dalam project default Anda). Perintah ini mengubah semua kolom REQUIRED di tabel tujuan menjadi NULLABLE.

bq query \
    --destination_table mydataset.mytable2 \
    --append_table \
    --schema_update_option=ALLOW_FIELD_RELAXATION \
    --use_legacy_sql=false \
    'SELECT
       column1,column2
     FROM
       mydataset.mytable'

Masukkan kueri perintah berikut mydataset.mytable dalam project default Anda dan untuk menambahkan hasil kueri ke mydataset.mytable2 di myotherproject. Perintah ini mengubah semua kolom REQUIRED di tabel tujuan menjadi NULLABLE.

bq query \
--destination_table myotherproject:mydataset.mytable2 \
--append_table \
--schema_update_option=ALLOW_FIELD_RELAXATION \
--use_legacy_sql=false \
'SELECT
   column1,column2
 FROM
   mydataset.mytable'

API

Panggil metode jobs.insert. Konfigurasikan tugas query dan setel properti berikut:

• Tentukan tabel tujuan menggunakan properti destinationTable.
• Tetapkan disposisi tulis tabel tujuan ke WRITE_APPEND menggunakan properti writeDisposition.
• Tentukan opsi pembaruan skema menggunakan properti schemaUpdateOptions.
• Tentukan kueri GoogleSQL menggunakan properti query.

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

// relaxTableQuery demonstrates relaxing the schema of a table by appending query results to
// enable the table to allow NULL values.
func relaxTableQuery(projectID, datasetID, tableID 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()

	sampleSchema := bigquery.Schema{
		{Name: "full_name", Type: bigquery.StringFieldType, Required: true},
		{Name: "age", Type: bigquery.IntegerFieldType, Required: true},
	}
	meta := &bigquery.TableMetadata{
		Schema: sampleSchema,
	}
	tableRef := client.Dataset(datasetID).Table(tableID)
	if err := tableRef.Create(ctx, meta); err != nil {
		return err
	}
	// Now, append a query result that includes nulls, but allow the job to relax
	// all required columns.
	q := client.Query("SELECT \"Beyonce\" as full_name")
	q.QueryConfig.Dst = client.Dataset(datasetID).Table(tableID)
	q.SchemaUpdateOptions = []string{"ALLOW_FIELD_RELAXATION"}
	q.WriteDisposition = bigquery.WriteAppend
	q.Location = "US"
	job, err := q.Run(ctx)
	if err != nil {
		return err
	}
	_, err = job.Wait(ctx)
	if 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.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.JobInfo.SchemaUpdateOption;
import com.google.cloud.bigquery.JobInfo.WriteDisposition;
import com.google.cloud.bigquery.QueryJobConfiguration;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableResult;
import com.google.common.collect.ImmutableList;

public class RelaxTableQuery {

  public static void runRelaxTableQuery() throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    relaxTableQuery(projectId, datasetName, tableName);
  }

  // To relax all columns in a destination table when you append data to it during a query job
  public static void relaxTableQuery(String projectId, String datasetName, String tableName)
      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);

      String sourceTable = "`" + projectId + "." + datasetName + "." + tableName + "`";
      String query = "SELECT word FROM " + sourceTable + " WHERE word like '%is%'";

      QueryJobConfiguration queryConfig =
          QueryJobConfiguration.newBuilder(query)
              // Use standard SQL syntax for queries.
              // See: https://cloud.google.com/bigquery/sql-reference/
              .setUseLegacySql(false)
              .setSchemaUpdateOptions(ImmutableList.of(SchemaUpdateOption.ALLOW_FIELD_RELAXATION))
              .setWriteDisposition(WriteDisposition.WRITE_APPEND)
              .setDestinationTable(tableId)
              .build();

      Job queryJob = bigquery.create(JobInfo.newBuilder(queryConfig).build());

      queryJob = queryJob.waitFor();

      // Check for errors
      if (queryJob == null) {
        throw new Exception("Job no longer exists");
      } else if (queryJob.getStatus().getError() != null) {
        // You can also look at queryJob.getStatus().getExecutionErrors() for all
        // errors, not just the latest one.
        throw new Exception(queryJob.getStatus().getError().toString());
      }

      // Get the results.
      TableResult results = queryJob.getQueryResults();

      // Print all pages of the results.
      results
          .iterateAll()
          .forEach(
              rows -> {
                rows.forEach(row -> System.out.println("row: " + row.toString()));
              });

      System.out.println("Successfully relaxed all columns in destination table during query job");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Columns not relaxed during query 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 destination table.
# table_id = "your-project.your_dataset.your_table_name"

# Retrieves the destination table and checks the number of required fields.
table = client.get_table(table_id)  # Make an API request.
original_required_fields = sum(field.mode == "REQUIRED" for field in table.schema)

# In this example, the existing table has 2 required fields.
print("{} fields in the schema are required.".format(original_required_fields))

# Configures the query to append the results to a destination table,
# allowing field relaxation.
job_config = bigquery.QueryJobConfig(
    destination=table_id,
    schema_update_options=[bigquery.SchemaUpdateOption.ALLOW_FIELD_RELAXATION],
    write_disposition=bigquery.WriteDisposition.WRITE_APPEND,
)

# Start the query, passing in the extra configuration.
query_job = client.query(
    # In this example, the existing table contains 'full_name' and 'age' as
    # required columns, but the query results will omit the second column.
    'SELECT "Beyonce" as full_name;',
    job_config=job_config,
)  # Make an API request.
query_job.result()  # Wait for the job to complete.

# Checks the updated number of required fields.
table = client.get_table(table_id)  # Make an API request.
current_required_fields = sum(field.mode == "REQUIRED" for field in table.schema)
print("{} fields in the schema are now required.".format(current_required_fields))

Mengubah nilai default kolom

Untuk mengubah nilai default kolom, pilih salah satu opsi berikut:

Konsol

1. Di konsol Google Cloud, buka halaman BigQuery.

   Buka BigQuery

2. Di panel Explorer, luaskan project dan set data Anda, lalu pilih tabel.

3. Di panel detail, klik tab Schema.

4. Klik Edit schema. Anda mungkin perlu men-scroll untuk melihat tombol ini.

5. Di halaman Current schema, cari kolom level teratas yang ingin Anda ubah.

6. Masukkan nilai default untuk kolom tersebut.

7. Klik Save.

SQL

Gunakan pernyataan DDL ALTER COLUMN SET DEFAULT.

1. Di konsol Google Cloud, buka halaman BigQuery.

   Buka BigQuery

2. Di editor kueri, masukkan pernyataan berikut:

   ALTER TABLE mydataset.mytable
   ALTER COLUMN column_name SET DEFAULT default_expression;

3. Klik Run.

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

Mengubah deskripsi kolom

Untuk mengubah deskripsi kolom, pilih salah satu opsi berikut:

Konsol

1. Di konsol Google Cloud, buka halaman BigQuery.

   Buka BigQuery

2. Di panel Explorer, luaskan project dan set data Anda, lalu pilih tabel.

3. Di panel detail, klik tab Schema.

4. Klik Edit schema. Anda mungkin perlu men-scroll untuk melihat tombol ini.

5. Di halaman Current schema, cari kolom yang ingin Anda ubah.

6. Masukkan deskripsi untuk kolom tersebut.

7. Klik Simpan.

SQL

Gunakan pernyataan DDL ALTER COLUMN SET OPTIONS.

1. Di konsol Google Cloud, buka halaman BigQuery.

   Buka BigQuery

2. Di editor kueri, masukkan pernyataan berikut:

   ALTER TABLE mydataset.mytable
   ALTER COLUMN column_name
   SET OPTIONS (description = 'This is a column description.');

3. Klik Run.

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

Menghapus kolom

Anda dapat menghapus kolom dari tabel yang sudah ada menggunakan pernyataan DDL ALTER TABLE DROP COLUMN.

Pernyataan tersebut tidak langsung mengosongkan penyimpanan yang terkait dengan kolom yang dihapus. Untuk mempelajari lebih lanjut dampak terhadap penyimpanan saat Anda menghapus kolom di penyimpanan, lihat detail pernyataan ALTER TABLE DROP COLUMN. Ada dua opsi untuk segera mengklaim kembali penyimpanan:

• Menimpa tabel dengan kueri SELECT * EXCEPT:

  CREATE OR REPLACE TABLE mydataset.mytable AS (
    SELECT * EXCEPT (column_to_delete) FROM mydataset.mytable
  );
  

• Mengekspor data ke Cloud Storage, menghapus kolom yang tidak diinginkan, lalu memuat data ke dalam tabel baru dengan skema yang benar.