Menetapkan skema

Dengan BigQuery, Anda dapat menentukan skema tabel saat memuat data ke dalam tabel, dan saat membuat tabel kosong. Atau, Anda dapat menggunakan deteksi otomatis skema untuk format data yang didukung.

Saat Anda memuat file ekspor Avro, Parquet, ORC, Firestore, atau file ekspor Datastore, skema ini secara otomatis diambil dari data sumber deskripsi mandiri.

Anda dapat menentukan skema tabel dengan cara berikut:

• Menggunakan Konsol Google Cloud.
• Menggunakan pernyataan SQL CREATE TABLE.
• Inline menggunakan alat command line bq.
• Membuat file skema dalam format JSON.
• Memanggil metode jobs.insert dan mengonfigurasikan properti schema di konfigurasi tugas load.
• Memanggil metode tables.insert dan mengonfigurasikan skema di resource tabel menggunakan properti schema.

Setelah memuat data atau membuat tabel kosong, Anda dapat mengubah definisi skema tabel.

Komponen skema

Saat menentukan skema tabel, Anda harus memberikan nama dan jenis data setiap kolom. Anda juga dapat memberikan deskripsi, mode, dan nilai default kolom.

Nama kolom

Nama kolom dapat berisi huruf (a-z, A-Z), angka (0-9), atau garis bawah (_), dan harus diawali dengan huruf atau garis bawah. Jika Anda menggunakan kolom fleksibel ini, BigQuery mendukung awal nama kolom dengan angka. Berhati-hatilah ketika memulai kolom dengan angka, karena penggunaan nama kolom dengan BigQuery Storage Read API atau BigQuery Storage Write API memerlukan penanganan khusus. Untuk mengetahui informasi selengkapnya tentang dukungan nama kolom fleksibel, lihat nama kolom yang fleksibel.

Nama kolom memiliki panjang maksimum 300 karakter. Nama kolom tidak dapat menggunakan dari awalan berikut ini:

• _TABLE_
• _FILE_
• _PARTITION
• _ROW_TIMESTAMP
• __ROOT__
• _COLIDENTIFIER

Nama kolom duplikat tidak diizinkan meskipun kasusnya berbeda. Sebagai contoh, kolom bernama Column1 dianggap sama dengan kolom bernama column1. Kepada mempelajari aturan penamaan kolom lebih lanjut, lihat Kolom nama pengguna di GoogleSQL.

Jika nama tabel (misalnya, test) sama dengan salah satu nama kolomnya (misalnya, test), ekspresi SELECT menafsirkan kolom test sebagai STRUCT yang berisi semua kolom tabel lainnya. Untuk menghindari tumbukan ini, gunakan salah satu metode berikut:

• Hindari penggunaan nama yang sama untuk tabel dan kolomnya.

• Tetapkan alias yang berbeda untuk tabel. Misalnya, kueri berikut menetapkan alias tabel t ke tabel project1.dataset.test:

  SELECT test FROM project1.dataset.test AS t;
  

• Sertakan nama tabel saat merujuk ke sebuah kolom. Contoh:

  SELECT test.test FROM project1.dataset.test;
  

Nama kolom fleksibel

Pratinjau

Produk atau fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum di Persyaratan Khusus Layanan. Produk dan fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Anda memiliki lebih banyak fleksibilitas dalam memberi nama kolom, termasuk akses yang diperluas menjadi karakter dalam bahasa selain bahasa Inggris serta simbol tambahan.

Nama kolom fleksibel mendukung karakter berikut:

• Huruf apa pun dalam bahasa apa pun, seperti yang diwakili oleh ekspresi reguler Unicode \p{L}
• Karakter numerik apa pun dalam bahasa apa pun sebagaimana diwakili oleh Unicode reguler ekspresi \p{N}
• Karakter tanda baca konektor apa pun, termasuk garis bawah, sebagaimana direpresentasikan oleh ekspresi reguler Unicode \p{Pc}
• Tanda hubung atau tanda pisah seperti yang diwakili oleh ekspresi reguler Unicode \p{Pd}.
• Tanda apa pun yang dimaksudkan untuk menyertai karakter lain sebagaimana diwakili oleh Ekspresi reguler unicode \p{M} Misalnya, aksen, umlaut, atau kotak penutup.
• Karakter khusus berikut:
  • Tanda dan (&) sebagaimana diwakili oleh reguler Unicode ekspresi \u0026.
  • Tanda persen (%) sebagaimana diwakili oleh Unicode reguler ekspresi \u0025.
  • Tanda sama dengan (=) sebagaimana diwakili oleh reguler Unicode ekspresi \u003D.
  • Tanda plus (+) sebagaimana diwakili oleh Unicode reguler ekspresi \u002B.
  • Titik dua (:) sebagaimana diwakili oleh reguler Unicode ekspresi \u003A.
  • Apostrof (') sebagaimana diwakili oleh reguler Unicode ekspresi \u0027.
  • Tanda lebih kecil dari (<) sebagaimana diwakili oleh reguler Unicode ekspresi \u003C.
  • Tanda lebih besar dari (>) seperti yang diwakili oleh reguler Unicode ekspresi \u003E.
  • Tanda angka (#) seperti yang diwakili oleh Unicode reguler ekspresi \u0023.
  • Garis vertikal (|) seperti yang diwakili oleh reguler Unicode ekspresi \u007c.
  • Spasi kosong.

Nama kolom fleksibel tidak mendukung karakter khusus berikut:

• Tanda seru (!) sebagaimana diwakili oleh reguler Unicode ekspresi \u0021.
• Tanda kutip (") sebagaimana diwakili oleh reguler Unicode ekspresi \u0022.
• Tanda dolar ($) sebagaimana diwakili oleh reguler Unicode ekspresi \u0024.
• Tanda kurung kiri (() seperti yang diwakili oleh reguler Unicode ekspresi \u0028.
• Tanda kurung kanan ()) seperti yang diwakili oleh reguler Unicode ekspresi \u0029.
• Tanda bintang (*) sebagaimana diwakili oleh reguler Unicode ekspresi \u002A.
• Koma (,) seperti yang diwakili oleh standar Unicode ekspresi \u002C.
• Titik (.) sebagaimana diwakili oleh reguler Unicode ekspresi \u002E.
• Garis miring (/) seperti yang diwakili oleh reguler Unicode ekspresi \u002F.
• Titik koma (;) sebagaimana diwakili oleh reguler Unicode ekspresi \u003B.
• Tanda tanya (?) sebagaimana diwakili oleh standar Unicode ekspresi \u003F.
• Tanda @ (@) sebagaimana diwakili oleh reguler Unicode ekspresi \u0040.
• Tanda kurung siku kiri ([) seperti yang diwakili oleh reguler Unicode ekspresi \u005B.
• Garis miring terbalik (\) seperti yang diwakili oleh reguler Unicode ekspresi \u005C.
• Tanda kurung siku kanan (]) seperti yang diwakili oleh reguler Unicode ekspresi \u005D.
• Aksen sirkumfleks (^) seperti yang diwakili oleh Unicode reguler ekspresi \u005E.
• Aksen nontirus (`) sebagaimana diwakili oleh reguler Unicode ekspresi \u0060.
• Tanda kurung kurawal buka {{) seperti yang diwakili oleh tanda kurung kurawal reguler Unicode ekspresi \u007B.
• Tanda kurung kurawal tutup (}) seperti yang diwakili oleh tanda kurung kurawal reguler Unicode ekspresi \u007D.
• Tanda gelombang (~) sebagaimana diwakili oleh ekspresi reguler Unicode \u007E.

Untuk panduan tambahan, lihat Nama kolom.

Karakter kolom yang diperluas didukung oleh BigQuery Storage Read API dan BigQuery Storage Write API. Untuk menggunakan daftar karakter Unicode yang diperluas dengan BigQuery Storage Read API, Anda harus menetapkan flag. Anda dapat menggunakan atribut displayName untuk mengambil nama kolom. Contoh berikut menunjukkan cara mengatur flag dengan klien Python:

from google.cloud.bigquery_storage import types
requested_session = types.ReadSession()

#set avro serialization options for flexible column.
options = types.AvroSerializationOptions()
options.enable_display_name_attribute = True
requested_session.read_options.avro_serialization_options = options

Untuk menggunakan daftar karakter Unicode yang diperluas dengan BigQuery Storage Write API, Anda harus memberikan skema dengan notasi column_name, kecuali jika Anda menggunakan objek tulis JsonStreamWriter. Contoh berikut menunjukkan cara berikan skema:

syntax = "proto2";
package mypackage;
// Source protos located in github.com/googleapis/googleapis
import "google/cloud/bigquery/storage/v1/annotations.proto";

message FlexibleSchema {
  optional string item_name_column = 1
  [(.google.cloud.bigquery.storage.v1.column_name) = "name-列"];
  optional string item_description_column = 2
  [(.google.cloud.bigquery.storage.v1.column_name) = "description-列"];
}

Dalam contoh ini, item_name_column dan item_description_column adalah nama placeholder yang harus mematuhi konvensi penamaan buffering protokol. Perhatikan bahwa anotasi column_name selalu lebih diutamakan daripada nama placeholder.

• Pemuatan data Parquet tidak mendukung nama kolom fleksibel secara default. Untuk mendaftar ke pratinjau ini, isi formulir pendaftaran. Perhatikan bahwa setelah mendaftar di pratinjau, nama kolom apa pun yang tidak valid (untuk contoh, kolasi nama kolom) mengembalikan {i>error<i}. Untuk project yang tidak terdaftar, permintaan pemuatan mengganti karakter yang tidak valid dengan garis bawah, bukan memunculkan {i>error<i}.
• Memuat data CSV menggunakan deteksi otomatis skema tidak mendukung nama kolom fleksibel secara default. Untuk mendaftar ke pratinjau ini, isi formulir pendaftaran. Perhatikan bahwa setelah mendaftar dalam pratinjau, setiap nama kolom yang tidak valid (misalnya, kolasi nama kolom) mengembalikan kesalahan. Untuk project yang tidak didaftarkan, permintaan pemuatan akan mengganti karakter yang tidak valid dengan garis bawah bukannya menampilkan pesan {i>error<i}.

Batasan

Nama kolom yang fleksibel tidak didukung dengan tabel eksternal.

Deskripsi kolom

Setiap kolom dapat berisi deskripsi opsional. Deskripsi adalah string dengan panjang maksimum 1.024 karakter.

Nilai default

Nilai default untuk kolom harus berupa literal atau salah satu dari fungsi berikut:

• CURRENT_DATE
• CURRENT_DATETIME
• CURRENT_TIME
• CURRENT_TIMESTAMP
• GENERATE_UUID
• RAND
• SESSION_USER
• ST_GEOGPOINT

Jenis data GoogleSQL

GoogleSQL memungkinkan Anda menentukan jenis data berikut dalam skema Anda. Jenis data wajib diisi.

Nama	Jenis data	Deskripsi
Bilangan Bulat	INT64	Nilai numerik tanpa komponen pecahan
Titik mengambang	FLOAT64	Perkiraan nilai numerik dengan komponen pecahan
Angka	NUMERIC	Nilai numerik yang tepat dengan komponen pecahan
BigNumeric	BIGNUMERIC	Nilai numerik yang tepat dengan komponen pecahan
Boolean	BOOL	TRUE atau FALSE (tidak peka huruf besar/kecil)
String	STRING	Data karakter dengan panjang variabel (Unicode)
Byte	BYTES	Data biner dengan panjang variabel
Tanggal	DATE	Tanggal kalender yang logis
Date/Time	DATETIME	Tahun, bulan, hari, jam, menit, detik, dan subdetik
Waktu	TIME	Waktu, terlepas dari tanggal tertentu
Stempel waktu	TIMESTAMP	Titik absolut dalam waktu, dengan presisi mikrodetik
Struktur (Kumpulan data)	STRUCT	Penampung kolom yang diurutkan masing-masing dengan jenis (wajib) dan nama kolom (opsional)
Geografi	GEOGRAPHY	Titik-titik di permukaan Bumi (kumpulan titik, garis, dan poligon pada bentuk bulat referensi WGS84, dengan tepi geodesi)
JSON	JSON	Mewakili JSON, format data-interchange yang ringan
RENTANG	RANGE	Rentang nilai DATE, DATETIME, atau TIMESTAMP

Untuk mengetahui informasi selengkapnya tentang jenis data di GoogleSQL, lihat Jenis data GoogleSQL.

Anda juga dapat mendeklarasikan jenis array saat melakukan kueri data. Untuk informasi selengkapnya, lihat Bekerja dengan array.

Mode

BigQuery mendukung mode berikut untuk kolom Anda. Mode bersifat opsional. Jika mode tidak ditentukan, kolom akan ditetapkan secara default ke NULLABLE.

Mode	Deskripsi
Nullable	Kolom mengizinkan nilai NULL (default)
Diperlukan	Nilai NULL tidak diizinkan
Berulang	Kolom berisi array nilai dari jenis yang ditentukan

Untuk informasi selengkapnya tentang moda, lihat mode di TableFieldSchema.

Mode pembulatan

Jika kolom berjenis NUMERIC atau BIGNUMERIC, Anda dapat menetapkan opsi kolom rounding_mode, yang menentukan cara pembulatan nilai dalam kolom tersebut saat ditulis ke tabel. Anda dapat menetapkan opsi rounding_mode di kolom level teratas atau kolom STRUCT. Mode pembulatan berikut didukung:

• "ROUND_HALF_AWAY_FROM_ZERO": Mode ini (default) membulatkan setengah kasus dari nol.
• "ROUND_HALF_EVEN": Mode ini membulatkan separuh kasus ke angka genap terdekat.

Anda tidak dapat menetapkan opsi rounding_mode untuk kolom yang bukan berjenis NUMERIC atau BIGNUMERIC. Untuk mempelajari jenis-jenis ini lebih lanjut, lihat jenis desimal.

Contoh berikut membuat tabel dan menyisipkan nilai yang dibulatkan berdasarkan mode pembulatan kolom:

CREATE TABLE mydataset.mytable (
  x NUMERIC(5,2) OPTIONS (rounding_mode='ROUND_HALF_EVEN'),
  y NUMERIC(5,2) OPTIONS (rounding_mode='ROUND_HALF_AWAY_FROM_ZERO')
);
INSERT mydataset.mytable (x, y)
VALUES (NUMERIC "1.025", NUMERIC "1.025"),
       (NUMERIC "1.0251", NUMERIC "1.0251"),
       (NUMERIC "1.035", NUMERIC "1.035"),
       (NUMERIC "-1.025", NUMERIC "-1.025");

Tabel mytable terlihat seperti berikut:

+-------+-------+
| x     | y     |
+-------+-------+
| 1.02  | 1.03  |
| 1.03  | 1.03  |
| 1.04  | 1.04  |
| -1.02 | -1.03 |
+-------+-------+

Untuk informasi selengkapnya, lihat roundingMode dalam TableFieldSchema.

Menentukan skema

Saat memuat data atau membuat tabel kosong, Anda dapat menentukan skema tabel menggunakan Google Cloud Console atau alat command line bq. Penentuan skema didukung saat Anda memuat file CSV dan JSON (newline delimited). Saat Anda memuat data ekspor Avro, Parquet, ORC, Firestore, atau data ekspor Datastore, skema ini secara otomatis diambil dari data sumber deskripsi mandiri.

Untuk menetapkan skema tabel:

Konsol

Di konsol Google Cloud, Anda dapat menentukan skema menggunakan opsi Add field atau opsi Edit as text.

1. Di Konsol Google Cloud, buka halaman BigQuery.

   Buka BigQuery

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

3. Luaskan opsi Actions dan klik Open.

4. Di panel detail, klik Create table .

5. Di halaman Create table, di bagian Source, pilih Empty table.

6. Di halaman Create table, di bagian Destination:

   • Untuk Dataset name, pilih set data yang sesuai

     

   • Di kolom Table name, masukkan nama tabel yang Anda buat.

   • Pastikan Table type disetel ke Native table.

7. Di bagian Schema, masukkan definisi skema.

   • Opsi 1: Gunakan Add field dan tentukan nama, jenis, dan mode setiap kolom.
   • Opsi 2: 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.

8. Klik Create table.

SQL

Gunakan pernyataan CREATE TABLE. Tentukan skema menggunakan opsi column. Contoh berikut membuat tabel baru bernama newtable dengan kolom x, y, z dengan jenis bilangan bulat, string, dan boolean:

1. Di konsol Google Cloud, buka halaman BigQuery.

   Buka BigQuery

2. Di editor kueri, masukkan pernyataan berikut:

   CREATE TABLE IF NOT EXISTS mydataset.newtable (x INT64, y STRING, z BOOL)
     OPTIONS(
       description = 'My example table');
   

3. Klik Run.

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

bq

Berikan skema secara inline dalam format field:data_type,field:data_type menggunakan salah satu perintah berikut:

• Jika Anda memuat data, gunakan perintah bq load.
• Jika Anda membuat tabel kosong, gunakan perintah bq mk.

Saat menentukan skema di command line, Anda tidak dapat menyertakan RECORD (STRUCT) atau RANGE Anda tidak dapat menyertakan deskripsi kolom, dan Anda tidak dapat menentukan mode kolom. Semua mode ditetapkan secara default ke NULLABLE. Kepada mencakup deskripsi, mode, jenis RECORD, dan jenis RANGE, menyediakan File skema JSON sebagai gantinya.

Untuk memuat data ke dalam tabel menggunakan definisi skema inline, masukkan perintah load dan tentukan format data menggunakan tanda --source_format. Jika Anda memuat data ke tabel dalam project selain project default Anda, sertakan project ID dalam format berikut: project_id:dataset.table_name.

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

bq --location=location load \
--source_format=format \
project_id:dataset.table_name \
path_to_source \
schema

Ganti kode berikut:

• 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.
• format: NEWLINE_DELIMITED_JSON atau CSV.
• project_id: project ID Anda.
• dataset: set data yang berisi tabel tempat Anda memuat data.
• table_name: nama tabel tempat Anda memuat data.
• path_to_source: lokasi file data CSV atau JSON di komputer lokal atau di Cloud Storage.
• schema: definisi skema inline.

Contoh:

Masukkan perintah berikut untuk memuat data dari file CSV lokal bernama myfile.csv ke mydataset.mytable di project default Anda. Skema ditentukan secara inline.

bq load \
--source_format=CSV \
mydataset.mytable \
./myfile.csv \
qtr:STRING,sales:FLOAT,year:STRING

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

Untuk menentukan definisi skema inline saat membuat tabel kosong, masukkan perintah bq mk dengan tanda --table atau -t. Jika Anda membuat tabel dalam project selain project default Anda, tambahkan project ID ke perintah dalam format berikut: project_id:dataset.table.

bq mk --table project_id:dataset.table schema

Ganti kode berikut:

• project_id: project ID Anda.
• dataset: set data di project Anda.
• table: nama tabel yang Anda buat.
• schema: definisi skema inline.

Misalnya, perintah berikut akan membuat tabel kosong bernama mytable di project default Anda. Skema ditentukan secara inline.

bq mk --table mydataset.mytable qtr:STRING,sales:FLOAT,year:STRING

Untuk informasi selengkapnya tentang pembuatan tabel kosong, lihat Membuat tabel kosong dengan definisi skema.

C#

Untuk menentukan skema tabel saat Anda memuat data ke dalam tabel:

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

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

using Google.Apis.Bigquery.v2.Data;
using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryLoadTableGcsJson
{
    public void LoadTableGcsJson(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var gcsURI = "gs://cloud-samples-data/bigquery/us-states/us-states.json";
        var dataset = client.GetDataset(datasetId);
        var schema = new TableSchemaBuilder {
            { "name", BigQueryDbType.String },
            { "post_abbr", BigQueryDbType.String }
        }.Build();
        TableReference destinationTableRef = dataset.GetTableReference(
            tableId: "us_states");
        // Create job configuration
        var jobOptions = new CreateLoadJobOptions()
        {
            SourceFormat = FileFormat.NewlineDelimitedJson
        };
        // Create and run job
        BigQueryJob loadJob = client.CreateLoadJob(
            sourceUri: gcsURI, destination: destinationTableRef,
            schema: schema, options: jobOptions);
        loadJob = loadJob.PollUntilCompleted().ThrowOnAnyError();  // Waits for the job to complete.
        // Display the number of rows uploaded
        BigQueryTable table = client.GetTable(destinationTableRef);
        Console.WriteLine(
            $"Loaded {table.Resource.NumRows} rows to {table.FullyQualifiedId}");
    }
}

Untuk menentukan skema saat Anda membuat tabel kosong:

using Google.Cloud.BigQuery.V2;

public class BigQueryCreateTable
{
    public BigQueryTable CreateTable(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var dataset = client.GetDataset(datasetId);
        // Create schema for new table.
        var schema = new TableSchemaBuilder
        {
            { "full_name", BigQueryDbType.String },
            { "age", BigQueryDbType.Int64 }
        }.Build();
        // Create the table
        return dataset.CreateTable(tableId: "your_table_id", schema: schema);
    }
}

Go

Untuk menentukan skema tabel saat Anda memuat data ke dalam tabel:

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

// importJSONExplicitSchema demonstrates loading newline-delimited JSON data from Cloud Storage
// into a BigQuery table and providing an explicit schema for the data.
func importJSONExplicitSchema(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()

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.json")
	gcsRef.SourceFormat = bigquery.JSON
	gcsRef.Schema = bigquery.Schema{
		{Name: "name", Type: bigquery.StringFieldType},
		{Name: "post_abbr", Type: bigquery.StringFieldType},
	}
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	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
}

Untuk menentukan skema saat Anda membuat tabel kosong:

import (
	"context"
	"fmt"
	"time"

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

// createTableExplicitSchema demonstrates creating a new BigQuery table and specifying a schema.
func createTableExplicitSchema(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: "full_name", Type: bigquery.StringFieldType},
		{Name: "age", Type: bigquery.IntegerFieldType},
	}

	metaData := &bigquery.TableMetadata{
		Schema:         sampleSchema,
		ExpirationTime: time.Now().AddDate(1, 0, 0), // Table will be automatically deleted in 1 year.
	}
	tableRef := client.Dataset(datasetID).Table(tableID)
	if err := tableRef.Create(ctx, metaData); err != nil {
		return err
	}
	return nil
}

Java

Untuk menentukan skema tabel saat Anda memuat data ke dalam tabel:

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

// Sample to load JSON data from Cloud Storage into a new BigQuery table
public class LoadJsonFromGCS {

  public static void runLoadJsonFromGCS() {
    // 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.json";
    Schema schema =
        Schema.of(
            Field.of("name", StandardSQLTypeName.STRING),
            Field.of("post_abbr", StandardSQLTypeName.STRING));
    loadJsonFromGCS(datasetName, tableName, sourceUri, schema);
  }

  public static void loadJsonFromGCS(
      String datasetName, String tableName, String sourceUri, Schema schema) {
    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);
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.newBuilder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.json())
              .setSchema(schema)
              .build();

      // Load data from a GCS JSON file into the table
      Job job = bigquery.create(JobInfo.of(loadConfig));
      // Blocks until this load table job completes its execution, either failing or succeeding.
      job = job.waitFor();
      if (job.isDone()) {
        System.out.println("Json from GCS 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());
    }
  }
}

Untuk menentukan skema saat Anda membuat tabel kosong:

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.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.StandardTableDefinition;
import com.google.cloud.bigquery.TableDefinition;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableInfo;

public class CreateTable {

  public static void runCreateTable() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    Schema schema =
        Schema.of(
            Field.of("stringField", StandardSQLTypeName.STRING),
            Field.of("booleanField", StandardSQLTypeName.BOOL));
    createTable(datasetName, tableName, schema);
  }

  public static void createTable(String datasetName, String tableName, Schema schema) {
    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);
      TableDefinition tableDefinition = StandardTableDefinition.of(schema);
      TableInfo tableInfo = TableInfo.newBuilder(tableId, tableDefinition).build();

      bigquery.create(tableInfo);
      System.out.println("Table created successfully");
    } catch (BigQueryException e) {
      System.out.println("Table was not created. \n" + e.toString());
    }
  }
}

Python

Untuk menentukan skema tabel saat Anda memuat data ke tabel, konfigurasikan properti LoadJobConfig.schema.

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(
    schema=[
        bigquery.SchemaField("name", "STRING"),
        bigquery.SchemaField("post_abbr", "STRING"),
    ],
    source_format=bigquery.SourceFormat.NEWLINE_DELIMITED_JSON,
)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.json"

load_job = client.load_table_from_uri(
    uri,
    table_id,
    location="US",  # Must match the destination dataset location.
    job_config=job_config,
)  # Make an API request.

load_job.result()  # Waits for the job to complete.

destination_table = client.get_table(table_id)
print("Loaded {} rows.".format(destination_table.num_rows))

Untuk menentukan skema saat membuat tabel kosong, konfigurasikan properti Table.schema.

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", mode="REQUIRED"),
    bigquery.SchemaField("age", "INTEGER", mode="REQUIRED"),
]

table = bigquery.Table(table_id, schema=schema)
table = client.create_table(table)  # Make an API request.
print(
    "Created table {}.{}.{}".format(table.project, table.dataset_id, table.table_id)
)

Menentukan file skema JSON

Jika ingin, Anda dapat menentukan skema menggunakan file skema JSON, bukan menggunakan definisi skema inline. File skema JSON terdiri dari array JSON yang berisi hal berikut:

• Nama kolom
• Jenis data kolom
• Opsional: Mode kolom (jika tidak ditentukan, mode akan ditetapkan secara default ke NULLABLE)
• Opsional: Kolom kolom jika berupa jenis STRUCT
• Opsional: Deskripsi kolom
• Opsional: Tag kebijakan pada kolom, digunakan untuk kontrol akses tingkat kolom
• Opsional: Panjang nilai maksimum kolom untuk jenis STRING atau BYTES
• Opsional: Presisi kolom untuk jenis NUMERIC atau BIGNUMERIC
• Opsional: Scale kolom untuk jenis NUMERIC atau BIGNUMERIC
• Opsional: Pengumpulan kolom untuk jenis STRING
• Opsional: Nilai default kolom
• Opsional: Mode pembulatan kolom, jika kolom berjenis NUMERIC atau BIGNUMERIC

Catatan: Anda juga dapat menentukan array JSON yang dibuat di file skema menggunakan opsi Edit as Text di Konsol Google Cloud. Properti ini juga dapat digunakan sebagai titik awal untuk mengonfigurasi properti schema di API.

Membuat file skema JSON

Untuk membuat file skema JSON, masukkan TableFieldSchema untuk setiap kolom. Kolom name dan type wajib diisi. Semua kolom lainnya bersifat opsional.

[
  {
    "name": string,
    "type": string,
    "mode": string,
    "fields": [
      {
        object (TableFieldSchema)
      }
    ],
    "description": string,
    "policyTags": {
      "names": [
        string
      ]
    },
    "maxLength": string,
    "precision": string,
    "scale": string,
    "collation": string,
    "defaultValueExpression": string,
    "roundingMode": string
  },
  {
    "name": string,
    "type": string,
    ...
  }
]

Jika kolom adalah jenis RANGE<T>, gunakan kolom rangeElementType untuk mendeskripsikan T, dengan T harus berupa salah satu dari DATE, DATETIME, atau TIMESTAMP.

[
  {
    "name": "duration",
    "type": "RANGE",
    "mode": "NULLABLE",
    "rangeElementType": {
      "type": "DATE"
    }
  }
]

Array JSON ditunjukkan dengan tanda kurung awal dan akhir []. Masing-masing entri kolom harus dipisahkan dengan koma: },.

Untuk menulis skema tabel yang ada ke file lokal, lakukan langkah berikut:

bq

bq show \
--schema \
--format=prettyjson \
project_id:dataset.table > path_to_file

Ganti kode berikut:

• project_id: project ID Anda.
• dataset: set data di project Anda.
• table: nama skema tabel yang ada.
• path_to_file: lokasi file lokal tempat file lokal Anda menulis skema tabel.

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.

Untuk menulis file JSON skema dari tabel menggunakan library klien Python, panggil metode Client.schema_to_json.

from google.cloud import bigquery

client = bigquery.Client()

# TODO(dev): Change the table_id variable to the full name of the
# table you want to get schema from.
table_id = "your-project.your_dataset.your_table_name"

# TODO(dev): Change schema_path variable to the path
# of your schema file.
schema_path = "path/to/schema.json"
table = client.get_table(table_id)  # Make an API request.

# Write a schema file to schema_path with the schema_to_json method.
client.schema_to_json(table.schema, schema_path)

with open(schema_path, "r", encoding="utf-8") as schema_file:
    schema_contents = schema_file.read()

# View table properties
print(f"Got table '{table.project}.{table.dataset_id}.{table.table_id}'.")
print(f"Table schema: {schema_contents}")

Anda dapat menggunakan file output sebagai titik awal untuk file skema JSON Anda sendiri. Jika Anda menggunakan pendekatan ini, pastikan file hanya berisi array JSON yang mewakili skema tabel.

Misalnya, array JSON berikut mewakili skema tabel dasar. Skema ini memiliki tiga kolom: qtr (REQUIRED STRING ), rep (NULLABLE STRING ), dansales (NULLABLE FLOAT ).

[
  {
    "name": "qtr",
    "type": "STRING",
    "mode": "REQUIRED",
    "description": "quarter"
  },
  {
    "name": "rep",
    "type": "STRING",
    "mode": "NULLABLE",
    "description": "sales representative"
  },
  {
    "name": "sales",
    "type": "FLOAT",
    "mode": "NULLABLE",
    "defaultValueExpression": "2.55"
  }
]

Menggunakan file skema JSON

Setelah membuat file skema JSON, Anda dapat menentukannya menggunakan alat command line bq. Anda tidak dapat menggunakan file skema dengan Google Cloud Console atau API.

Berikan file skema:

• Jika Anda memuat data, gunakan perintah bq load.
• Jika Anda membuat tabel kosong, gunakan perintah bq mk.

Jika Anda memberikan file skema JSON, file tersebut harus disimpan di lokasi yang dapat dibaca secara lokal. Anda tidak dapat menentukan file skema JSON yang disimpan di Cloud Storage atau Google Drive.

Menentukan file skema saat memuat data

Untuk memuat data ke dalam tabel menggunakan definisi skema JSON, lakukan hal berikut:

bq

bq --location=location load \
--source_format=format \
project_id:dataset.table \
path_to_data_file \
path_to_schema_file

Ganti kode berikut:

• location: nama lokasi Anda. Flag --location bersifat opsional. Misalnya, jika menggunakan BigQuery di wilayah Tokyo, Anda dapat menetapkan nilai tanda ke asia-northeast1. Anda dapat menetapkan nilai default untuk lokasi menggunakan file .bigqueryrc.
• format: NEWLINE_DELIMITED_JSON atau CSV.
• project_id: project ID Anda.
• dataset: set data yang berisi tabel tempat Anda memuat data.
• table: nama tabel tempat Anda memuat data.
• path_to_data_file: lokasi file data CSV atau JSON di komputer lokal atau di Cloud Storage.
• path_to_schema_file: jalur ke file skema di komputer lokal Anda.

Contoh:

Masukkan perintah berikut untuk memuat data dari file CSV lokal bernama myfile.csv ke mydataset.mytable di project default Anda. Skema ditentukan dalam myschema.json di direktori saat ini.

bq load --source_format=CSV mydataset.mytable ./myfile.csv ./myschema.json

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.

Untuk memuat skema tabel dari file JSON menggunakan library klien Python, panggil metode schema_from_json.

from google.cloud import bigquery

client = bigquery.Client()

# TODO(dev): Change uri variable to the path of your data file.
uri = "gs://your-bucket/path/to/your-file.csv"
# TODO(dev): Change table_id to the full name of the table you want to create.
table_id = "your-project.your_dataset.your_table"
# TODO(dev): Change schema_path variable to the path of your schema file.
schema_path = "path/to/schema.json"
# To load a schema file use the schema_from_json method.
schema = client.schema_from_json(schema_path)

job_config = bigquery.LoadJobConfig(
    # To use the schema you loaded pass it into the
    # LoadJobConfig constructor.
    schema=schema,
    skip_leading_rows=1,
)

# Pass the job_config object to the load_table_from_file,
# load_table_from_json, or load_table_from_uri method
# to use the schema on a new table.
load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

load_job.result()  # Waits for the job to complete.

destination_table = client.get_table(table_id)  # Make an API request.
print(f"Loaded {destination_table.num_rows} rows to {table_id}.")

Menetapkan file skema saat Anda membuat tabel

Untuk membuat tabel kosong dalam set data yang ada menggunakan file skema JSON, lakukan hal berikut:

bq

bq mk --table project_id:dataset.table path_to_schema_file

Ganti kode berikut:

• project_id: project ID Anda.
• dataset: set data di project Anda.
• table: nama tabel yang Anda buat.
• path_to_schema_file: jalur ke file skema di komputer lokal Anda.

Misalnya, perintah berikut akan membuat tabel bernama mytable di mydataset dalam project default Anda. Skema ditentukan dalam myschema.json dalam direktori saat ini:

bq mk --table mydataset.mytable ./myschema.json

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.

Untuk memuat skema tabel dari file JSON menggunakan library klien Python, panggil metode schema_from_json.

from google.cloud import bigquery

client = bigquery.Client()

# TODO(dev): Change table_id to the full name of the table you want to create.
table_id = "your-project.your_dataset.your_table_name"
# TODO(dev): Change schema_path variable to the path of your schema file.
schema_path = "path/to/schema.json"
# To load a schema file use the schema_from_json method.
schema = client.schema_from_json(schema_path)

table = bigquery.Table(table_id, schema=schema)
table = client.create_table(table)  # API request
print(f"Created table {table_id}.")

Menetapkan skema di API

Tetapkan skema tabel menggunakan API:

• Untuk menentukan skema saat memuat data, panggil metode jobs.insert dan konfigurasi properti schema di referensi JobConfigurationLoad.

• Untuk menentukan skema saat membuat tabel, panggil metode tables.insert dan konfigurasi schema di resource Table.

Menentukan skema menggunakan API mirip dengan proses Membuat file skema JSON.

Keamanan tabel

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

Langkah selanjutnya

• Pelajari cara menentukan kolom bertingkat dan berulang dalam definisi skema.
• Pelajari deteksi otomatis skema.
• Pelajari cara memuat data ke BigQuery.
• Pelajari cara membuat dan menggunakan tabel.