Memuat data Parquet dari Cloud Storage

Halaman ini menyediakan ringkasan pemuatan data Parquet dari Cloud Storage ke BigQuery.

Parquet adalah format data berorientasi kolom open source yang banyak digunakan di ekosistem Apache Hadoop.

Saat memuat data Parquet dari Cloud Storage, Anda dapat memuat data tersebut ke dalam tabel atau partisi baru, atau Anda dapat menambahkan ke atau menimpa tabel atau partisi yang sudah ada. Setelah dimuat ke BigQuery, data Anda akan dikonversi ke dalam format berbasis kolom untuk Capacitor (format penyimpanan BigQuery).

Saat Anda memuat data dari Cloud Storage ke tabel BigQuery, set data yang berisi tabel harus berada di lokasi regional atau multi-regional yang sama dengan bucket Cloud Storage.

Untuk informasi tentang memuat data Parquet dari file lokal, lihat Memuat data dari file lokal.

Batasan

Anda harus tunduk kepada batasan berikut saat memuat data ke BigQuery dari bucket Cloud Storage:

• Jika lokasi set data Anda ditetapkan ke nilai selain multi-region US, bucket Cloud Storage harus berada di region yang sama atau berada dalam multi-region yang sama dengan set data tersebut.
• BigQuery tidak menjamin konsistensi data untuk sumber data eksternal. Perubahan pada data yang mendasari saat kueri berjalan dapat menyebabkan perilaku yang tidak terduga.

• BigQuery tidak mendukung pembuatan versi objek Cloud Storage. Jika Anda menyertakan nomor pembuatan dalam URI Cloud Storage, tugas pemuatan akan gagal.

• Pemuatan data Parquet tidak mendukung nama kolom fleksibel secara default. Untuk mendaftar dalam pratinjau ini, isi formulir pendaftaran.

• Anda tidak dapat menggunakan karakter pengganti di URI Cloud Storage jika salah satu file yang akan dimuat memiliki skema yang berbeda. Perbedaan apa pun pada posisi kolom memenuhi syarat sebagai skema yang berbeda.

Persyaratan file input

Untuk menghindari error resourcesExceeded saat memuat file Parquet ke BigQuery, ikuti panduan berikut:

• Batasi ukuran baris maksimal 50 MB.
• Jika data input Anda berisi lebih dari 100 kolom, pertimbangkan untuk mengurangi ukuran halaman agar lebih kecil dari ukuran halaman default (1 * 1024 * 1024 byte). Hal ini sangat membantu jika Anda menggunakan kompresi yang signifikan.

Sebelum memulai

Berikan peran Identity and Access Management (IAM) yang memberi pengguna izin yang diperlukan untuk melakukan setiap tugas dalam dokumen ini, dan buat set data untuk menyimpan data Anda.

Izin yang diperlukan

Untuk memuat data ke BigQuery, Anda memerlukan izin IAM untuk menjalankan tugas pemuatan dan memuat data ke dalam tabel dan partisi BigQuery. Jika memuat data dari Cloud Storage, Anda juga memerlukan izin IAM untuk mengakses bucket yang berisi data Anda.

Izin untuk memuat data ke BigQuery

Untuk memuat data ke dalam tabel atau partisi BigQuery baru, atau menambahkan atau menimpa tabel atau partisi yang sudah ada, Anda memerlukan izin IAM berikut:

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

Setiap peran IAM yang telah ditetapkan berikut mencakup izin yang diperlukan untuk memuat data ke dalam tabel atau partisi BigQuery:

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

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

Untuk mengetahui informasi selengkapnya tentang peran dan izin IAM di BigQuery, lihat Peran dan izin yang telah ditetapkan.

Izin untuk memuat data dari Cloud Storage

Untuk mendapatkan izin yang Anda perlukan untuk memuat data dari bucket Cloud Storage, minta administrator untuk memberi Anda peran IAM Storage Admin (roles/storage.admin) di bucket. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses.

Peran yang telah ditetapkan ini berisi izin yang diperlukan untuk memuat data dari bucket Cloud Storage. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk memuat data dari bucket Cloud Storage:

• storage.buckets.get
• storage.objects.get
• storage.objects.list (required if you are using a URI wildcard)

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran lainnya yang telah ditetapkan sebelumnya.

Membuat set data

Membuat set data BigQuery untuk menyimpan data Anda.

Skema Parquet

Saat Anda memuat file Parquet ke BigQuery, skema tabel diambil secara otomatis dari data sumber yang mendeskripsikan sendiri. Saat BigQuery mengambil skema dari data sumber, file terakhir menurut abjad akan digunakan.

Misalnya, Anda memiliki file Parquet berikut di Cloud Storage:

gs://mybucket/00/
  a.parquet
  z.parquet
gs://mybucket/01/
  b.parquet

Menjalankan perintah ini di alat command line bq akan memuat semua file (sebagai daftar yang dipisahkan koma), dan skemanya berasal dari mybucket/01/b.parquet:

bq load \
--source_format=PARQUET \
dataset.table \
"gs://mybucket/00/*.parquet","gs://mybucket/01/*.parquet"

Saat Anda memuat beberapa file Parquet yang memiliki skema berbeda, kolom identik yang ditentukan dalam beberapa skema harus memiliki mode yang sama di setiap definisi skema.

Saat BigQuery mendeteksi skema, beberapa jenis data Parquet akan dikonversi ke jenis data BigQuery agar kompatibel dengan sintaksis GoogleSQL. Untuk informasi selengkapnya, lihat Konversi parquet.

Guna menyediakan skema tabel untuk membuat tabel eksternal, tetapkan properti referenceFileSchemaUri di BigQuery API atau parameter
--reference_file_schema_uri di alat command line bq ke URL file referensi.

Misalnya, --reference_file_schema_uri="gs://mybucket/schema.parquet".

Kompresi Parquet

BigQuery mendukung codec kompresi berikut untuk konten file Parquet:

• GZip
• LZO_1C
• LZO_1X
• LZ4_RAW
• Snappy
• ZSTD

Memuat data Parquet ke tabel baru

Anda dapat memuat data Parquet ke dalam tabel baru menggunakan salah satu opsi berikut:

• Konsol Google Cloud
• Perintah bq load alat command line bq
• Metode API jobs.insert dan mengonfigurasi tugas load
• Library klien

Untuk memuat data Parquet dari Cloud Storage ke tabel BigQuery yang baru:

Konsol

1. Di konsol Google Cloud, buka halaman BigQuery.

   Buka BigQuery

2. Di panel Explorer, luaskan project Anda, lalu pilih set data.
3. Di bagian Dataset info, klik Create table.
4. Di panel Create table, tentukan detail berikut:
1. Di bagian Source, pilih Google Cloud Storage dalam daftar Create table from. Kemudian, lakukan hal berikut:
   1. Pilih file dari bucket Cloud Storage, atau masukkan Cloud Storage URI. Anda tidak dapat menyertakan beberapa URI di Konsol Google Cloud, tetapi karakter pengganti bisa didukung. Bucket Cloud Storage harus berada di lokasi yang sama dengan set data yang berisi tabel yang ingin Anda buat, tambahkan, atau timpa.
   2. Untuk File format, pilih Parquet.
2. Di bagian Destination, tentukan detail berikut:
   1. Untuk Dataset, pilih set data tempat Anda ingin membuat tabel.
   2. Di kolom Table, masukkan nama tabel yang ingin Anda buat.
   3. Pastikan kolom Table type disetel ke Native table.
3. Di bagian Schema, Anda tidak perlu melakukan tindakan apa pun. Skema ini dijelaskan sendiri dalam file Parquet.
4. Opsional: Tentukan Partition and cluster settings. Untuk mengetahui informasi selengkapnya, lihat Membuat tabel berpartisi serta Membuat dan menggunakan tabel yang dikelompokkan.
5. Klik Advanced options, lalu lakukan tindakan berikut:
   • Untuk Write preference, biarkan Write if empty dipilih. Opsi ini akan membuat tabel baru dan memuat data Anda ke dalamnya.
   • Jika Anda ingin mengabaikan nilai dalam baris yang tidak ada dalam skema tabel, pilih Unknown values.
   • Untuk Encryption, klik Customer-managed key untuk menggunakan kunci Cloud Key Management Service. Jika Anda membiarkan setelan Google-managed key, BigQuery akan mengenkripsi data dalam penyimpanan.
6. Klik Buat tabel.

Catatan: Saat memuat data ke tabel kosong menggunakan Konsol Google Cloud, Anda tidak dapat menambahkan label, deskripsi, masa berlaku tabel, atau tanggal habis masa berlaku partisi.

Setelah tabel dibuat, Anda dapat memperbarui masa berlaku, deskripsi, dan label tabel, tetapi Anda tidak dapat menambahkan tanggal habis masa berlaku partisi setelah tabel dibuat menggunakan Konsol Google Cloud. Untuk mengetahui informasi selengkapnya, lihat Mengelola tabel.

SQL

Gunakan pernyataan DDL LOAD DATA. Contoh berikut memuat file Parquet ke tabel baru mytable:

1. Di Konsol Google Cloud, buka halaman BigQuery.

   Buka BigQuery

2. Di editor kueri, masukkan pernyataan berikut:

   LOAD DATA OVERWRITE mydataset.mytable
   FROM FILES (
     format = 'PARQUET',
     uris = ['gs://bucket/path/file.parquet']);
   

3. Klik Run.

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

bq

Gunakan perintah bq load, tentukan PARQUET menggunakan flag --source_format, dan sertakan Cloud Storage URI. Anda dapat menyertakan satu URI, daftar URI yang dipisahkan koma, atau URI yang berisi karakter pengganti.

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

Flag opsional lainnya meliputi:

• --time_partitioning_type: Mengaktifkan partisi berbasis waktu pada tabel dan menetapkan jenis partisi. Nilai yang mungkin adalah HOUR, DAY, MONTH, dan YEAR. Flag ini bersifat opsional saat Anda membuat tabel yang dipartisi pada kolom DATE, DATETIME, atau TIMESTAMP. Jenis partisi default untuk partisi berbasis waktu adalah DAY. Anda tidak dapat mengubah spesifikasi partisi pada tabel yang ada.
• --time_partitioning_expiration: Bilangan bulat yang menentukan (dalam detik) kapan partisi berbasis waktu harus dihapus. Waktu habis masa berlaku bernilai tanggal UTC partisi ditambah nilai bilangan bulat.
• --time_partitioning_field: Kolom DATE atau TIMESTAMP yang digunakan untuk membuat tabel yang dipartisi. Jika partisi berbasis waktu diaktifkan tanpa nilai ini, tabel berpartisi berdasarkan waktu penyerapan akan dibuat.
• --require_partition_filter: Jika diaktifkan, opsi ini mengharuskan pengguna menyertakan klausa WHERE yang menentukan partisi yang akan dikueri. Mewajibkan filter partisi dapat mengurangi biaya dan meningkatkan performa. Untuk mengetahui informasi selengkapnya, lihat Membuat kueri tabel berpartisi.
• --clustering_fields: Daftar yang dipisahkan koma yang berisi maksimum empat nama kolom yang digunakan untuk membuat tabel yang dikelompokkan.

• --destination_kms_key: Kunci Cloud KMS untuk enkripsi data tabel.

  Untuk mengetahui informasi selengkapnya tentang tabel berpartisi, lihat:

  • Membuat tabel berpartisi

  Untuk mengetahui informasi selengkapnya tentang tabel yang dikelompokkan, lihat:

  • Membuat dan menggunakan tabel yang dikelompokkan

  Untuk mengetahui informasi selengkapnya tentang enkripsi tabel, lihat:

  • Melindungi data dengan kunci Cloud KMS

Untuk memuat data Parquet ke BigQuery, masukkan perintah berikut:

bq --location=LOCATION load \
--source_format=FORMAT \
DATASET.TABLE \
PATH_TO_SOURCE

Ganti kode berikut:

• LOCATION: 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: PARQUET.
• DATASET: set data yang sudah ada.
• TABLE: nama tabel tempat Anda memuat data.
• PATH_TO_SOURCE: Cloud Storage URI yang sepenuhnya memenuhi syarat atau daftar URI yang dipisahkan koma. Karakter pengganti juga didukung.

Contoh:

Perintah berikut memuat data dari gs://mybucket/mydata.parquet ke tabel bernama mytable di mydataset.

    bq load \
    --source_format=PARQUET \
    mydataset.mytable \
    gs://mybucket/mydata.parquet

Perintah berikut memuat data dari gs://mybucket/mydata.parquet ke tabel berpartisi berdasarkan waktu penyerapan baru bernama mytable di mydataset.

    bq load \
    --source_format=PARQUET \
    --time_partitioning_type=DAY \
    mydataset.mytable \
    gs://mybucket/mydata.parquet

Perintah berikut memuat data dari gs://mybucket/mydata.parquet ke tabel berpartisi dengan nama mytable di mydataset. Tabel dipartisi pada kolom mytimestamp.

    bq load \
    --source_format=PARQUET \
    --time_partitioning_field mytimestamp \
    mydataset.mytable \
    gs://mybucket/mydata.parquet

Perintah berikut memuat data dari beberapa file di gs://mybucket/ ke dalam tabel bernama mytable di mydataset. Cloud Storage URI menggunakan karakter pengganti.

    bq load \
    --source_format=PARQUET \
    mydataset.mytable \
    gs://mybucket/mydata*.parquet

Perintah berikut memuat data dari beberapa file di gs://mybucket/ ke dalam tabel bernama mytable di mydataset. Perintah ini menyertakan daftar Cloud Storage URI yang dipisahkan koma dengan karakter pengganti.

    bq load \
    --source_format=PARQUET \
    mydataset.mytable \
    "gs://mybucket/00/*.parquet","gs://mybucket/01/*.parquet"

API

1. Buat tugas load yang mengarah ke data sumber di Cloud Storage.

2. (Opsional) Tentukan lokasi Anda di properti location di bagian jobReference pada resource tugas.

3. Properti source URIs harus sepenuhnya memenuhi syarat, dalam format gs://BUCKET/OBJECT. Setiap URI dapat berisi satu karakter pengganti '*'.

4. Tentukan format data Parquet dengan menetapkan properti sourceFormat ke PARQUET.

5. Untuk memeriksa status tugas, panggil jobs.get(JOB_ID*), dengan mengganti JOB_ID dengan ID tugas yang ditampilkan oleh permintaan awal.

   • Jika status.state = DONE, tugas berhasil diselesaikan.
   • Jika properti status.errorResult ada, permintaan gagal, dan objek tersebut menyertakan informasi yang menjelaskan apa yang salah. Jika permintaan gagal, tidak ada tabel yang dibuat dan tidak ada data yang dimuat.
   • Jika status.errorResult tidak ada, tugas berhasil diselesaikan; meskipun mungkin ada beberapa error non-fatal, seperti masalah mengimpor beberapa baris. Error non-fatal tercantum dalam properti status.errors objek tugas yang ditampilkan.

Catatan API:

• Tugas pemuatan bersifat atomik dan konsisten: jika tugas pemuatan gagal, tidak ada data yang tersedia, dan jika tugas pemuatan berhasil, semua data akan tersedia.

• Sebagai praktik terbaik, buat ID unik dan teruskan sebagai jobReference.jobId saat memanggil jobs.insert untuk membuat tugas pemuatan. Pendekatan ini lebih tangguh untuk kegagalan jaringan karena klien dapat melakukan polling atau mencoba ulang ID tugas yang diketahui.

• Memanggil jobs.insert pada ID tugas tertentu bersifat idempoten. Anda dapat mencoba lagi sebanyak yang Anda inginkan pada ID tugas yang sama, dan maksimal satu dari operasi tersebut akan berhasil.

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 mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

import (
	"context"
	"fmt"

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

// importParquet demonstrates loading Apache Parquet data from Cloud Storage into a table.
func importParquet(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.parquet")
	gcsRef.SourceFormat = bigquery.Parquet
	gcsRef.AutoDetect = true
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)

	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}

	if status.Err() != nil {
		return fmt.Errorf("job completed with error: %v", status.Err())
	}
	return nil
}

Java

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

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui 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.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.TableId;
import java.math.BigInteger;

public class LoadParquet {

  public static void runLoadParquet() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    loadParquet(datasetName);
  }

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

      String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.parquet";
      TableId tableId = TableId.of(datasetName, "us_states");

      LoadJobConfiguration configuration =
          LoadJobConfiguration.builder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.parquet())
              .build();

      // For more information on Job see:
      // https://googleapis.dev/java/google-cloud-clients/latest/index.html?com/google/cloud/bigquery/package-summary.html
      // Load the table
      Job job = bigquery.create(JobInfo.of(configuration));

      // Blocks until this load table job completes its execution, either failing or succeeding.
      Job completedJob = job.waitFor();
      if (completedJob == null) {
        System.out.println("Job not executed since it no longer exists.");
        return;
      } else if (completedJob.getStatus().getError() != null) {
        System.out.println(
            "BigQuery was unable to load the table due to an error: \n"
                + job.getStatus().getError());
        return;
      }

      // Check number of rows loaded into the table
      BigInteger numRows = bigquery.getTable(tableId).getNumRows();
      System.out.printf("Loaded %d rows. \n", numRows);

      System.out.println("GCS parquet loaded successfully.");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("GCS Parquet was not loaded. \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 mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

// Instantiate clients
const bigquery = new BigQuery();
const storage = new Storage();

/**
 * This sample loads the Parquet file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.parquet
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.parquet';

async function loadTableGCSParquet() {
  // Imports a GCS file into a table with Parquet source format.

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

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const metadata = {
    sourceFormat: 'PARQUET',
    location: 'US',
  };

  // Load data from a Google Cloud Storage file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(storage.bucket(bucketName).file(filename), metadata);

  // load() waits for the job to finish
  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;
  }
}

PHP

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

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

use Google\Cloud\BigQuery\BigQueryClient;
use Google\Cloud\Core\ExponentialBackoff;

/** Uncomment and populate these variables in your code */
// $projectId  = 'The Google project ID';
// $datasetId  = 'The BigQuery dataset ID';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table('us_states');

// create the import job
$gcsUri = 'gs://cloud-samples-data/bigquery/us-states/us-states.parquet';
$loadConfig = $table->loadFromStorage($gcsUri)->sourceFormat('PARQUET');
$job = $table->runJob($loadConfig);
// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    print('Waiting for job to complete' . PHP_EOL);
    $job->reload();
    if (!$job->isComplete()) {
        throw new Exception('Job has not yet completed', 500);
    }
});
// check if the job has errors
if (isset($job->info()['status']['errorResult'])) {
    $error = $job->info()['status']['errorResult']['message'];
    printf('Error running job: %s' . PHP_EOL, $error);
} else {
    print('Data imported successfully' . PHP_EOL);
}

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 mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Gunakan metode Client.load_table_from_uri() untuk memulai tugas pemuatan dari Cloud Storage. Untuk menggunakan Parquet, tetapkan properti LoadJobConfig.source_format ke string PARQUET dan teruskan konfigurasi tugas sebagai argumen job_config ke metode load_table_from_uri().

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(
    source_format=bigquery.SourceFormat.PARQUET,
)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.parquet"

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)
print("Loaded {} rows.".format(destination_table.num_rows))

Menambahkan ke atau menimpa tabel dengan data Parquet

Anda dapat memuat data tambahan ke dalam tabel dari file sumber atau dengan menambahkan hasil kueri.

Di Konsol Google Cloud, gunakan opsi Write preference untuk menentukan tindakan yang harus diambil ketika Anda memuat data dari file sumber atau dari hasil kueri.

Anda memiliki opsi berikut saat memuat data tambahan ke dalam tabel:

Opsi konsol	flag alat bq	Properti BigQuery API	Deskripsi
Tulis jika kosong	Tidak didukung	WRITE_EMPTY	Menulis data hanya jika tabel kosong.
Tambahkan ke tabel	--noreplace atau --replace=false; jika --[no]replace tidak ditentukan, defaultnya adalah menambahkan	WRITE_APPEND	(Default) Menambahkan data ke akhir tabel.
Timpa tabel	--replace atau --replace=true	WRITE_TRUNCATE	Menghapus semua data yang ada di tabel sebelum menulis data baru. Tindakan ini juga akan menghapus skema tabel dan keamanan tingkat baris, serta menghapus kunci Cloud KMS apa pun.

Jika Anda memuat data ke dalam tabel yang sudah ada, tugas pemuatan dapat menambahkan data atau menimpa tabel.

Anda dapat menambahkan atau menimpa tabel menggunakan salah satu cara berikut:

• Konsol Google Cloud
• Perintah bq load alat command line bq
• Metode API jobs.insert dan mengonfigurasi tugas load
• Library klien

Catatan: Halaman ini tidak mencakup penambahan atau penimpaan tabel berpartisi. Untuk mengetahui informasi tentang cara menambahkan dan menimpa tabel berpartisi, lihat: Menambahkan dan menimpa data tabel yang dipartisi.

Untuk menambahkan atau menimpa tabel dengan data Parquet:

Konsol

1. Di konsol Google Cloud, buka halaman BigQuery.

   Buka BigQuery

2. Di panel Explorer, luaskan project Anda, lalu pilih set data.
3. Di bagian Dataset info, klik Create table.
4. Di panel Create table, tentukan detail berikut:
1. Di bagian Source, pilih Google Cloud Storage dalam daftar Create table from. Kemudian, lakukan hal berikut:
   1. Pilih file dari bucket Cloud Storage, atau masukkan Cloud Storage URI. Anda tidak dapat menyertakan beberapa URI di Konsol Google Cloud, tetapi karakter pengganti bisa didukung. Bucket Cloud Storage harus berada di lokasi yang sama dengan set data yang berisi tabel yang ingin Anda buat, tambahkan, atau timpa.
   2. Untuk File format, pilih Parquet.
Catatan: Skema tabel dapat diubah saat Anda menambahkan atau menimpanya. Untuk mengetahui informasi selengkapnya tentang perubahan skema yang didukung selama operasi pemuatan, lihat Mengubah skema tabel.
2. Di bagian Destination, tentukan detail berikut:
   1. Untuk Dataset, pilih set data tempat Anda ingin membuat tabel.
   2. Di kolom Table, masukkan nama tabel yang ingin Anda buat.
   3. Pastikan kolom Table type disetel ke Native table.
3. Di bagian Schema, Anda tidak perlu melakukan tindakan apa pun. Skema ini dijelaskan sendiri dalam file Parquet.
Catatan: Skema tabel dapat diubah saat Anda menambahkan atau menimpanya. Untuk mengetahui informasi selengkapnya tentang perubahan skema yang didukung selama operasi pemuatan, lihat Mengubah skema tabel.
4. Opsional: Tentukan Partition and cluster settings. Untuk mengetahui informasi selengkapnya, lihat Membuat tabel berpartisi serta Membuat dan menggunakan tabel yang dikelompokkan. Anda tidak dapat mengonversi tabel menjadi tabel berpartisi atau tabel yang dikelompokkan dengan menambahkan atau menimpanya. Konsol Google Cloud tidak mendukung penambahan ke atau penimpaan tabel berpartisi atau tabel yang dikelompokkan dalam tugas pemuatan.
5. Klik Advanced options, lalu lakukan tindakan berikut:
   • Untuk Write preference, pilih Append to table atau Overwrite table.
   • Jika Anda ingin mengabaikan nilai dalam baris yang tidak ada dalam skema tabel, pilih Unknown values.
   • Untuk Encryption, klik Customer-managed key untuk menggunakan kunci Cloud Key Management Service. Jika Anda membiarkan setelan Google-managed key, BigQuery akan mengenkripsi data dalam penyimpanan.
6. Klik Buat tabel.

SQL

Gunakan pernyataan DDL LOAD DATA. Contoh berikut menambahkan file Parquet ke tabel mytable:

1. Di Konsol Google Cloud, buka halaman BigQuery.

   Buka BigQuery

2. Di editor kueri, masukkan pernyataan berikut:

   LOAD DATA INTO mydataset.mytable
   FROM FILES (
     format = 'PARQUET',
     uris = ['gs://bucket/path/file.parquet']);
   

3. Klik Run.

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

bq

Masukkan perintah bq load dengan flag --replace untuk menimpa tabel. Gunakan flag --noreplace untuk menambahkan data ke tabel. Jika tidak ada flag yang ditentukan, defaultnya adalah menambahkan data. Berikan flag --source_format dan tetapkan ke PARQUET. Karena skema Parquet diambil secara otomatis dari data sumber yang mendeskripsikan sendiri, Anda tidak perlu memberikan definisi skema.

Catatan: Skema tabel dapat diubah saat Anda menambahkan atau menimpanya. Untuk mengetahui informasi selengkapnya tentang perubahan skema yang didukung selama operasi pemuatan, lihat Mengubah skema tabel.

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

Flag opsional lainnya meliputi:

• --destination_kms_key: Kunci Cloud KMS untuk enkripsi data tabel.

bq --location=LOCATION load \
--[no]replace \
--source_format=FORMAT \
DATASET.TABLE \
PATH_TO_SOURCE

Ganti kode berikut:

• location: lokasi Anda. Flag --location bersifat opsional. Anda dapat menetapkan nilai default untuk lokasi menggunakan file .bigqueryrc.
• format: PARQUET.
• dataset: set data yang sudah ada.
• table: nama tabel tempat Anda memuat data.
• path_to_source: Cloud Storage URI yang sepenuhnya memenuhi syarat atau daftar URI yang dipisahkan koma. Karakter pengganti juga didukung.

Contoh:

Perintah berikut memuat data dari gs://mybucket/mydata.parquet dan menimpa tabel bernama mytable di mydataset.

    bq load \
    --replace \
    --source_format=PARQUET \
    mydataset.mytable \
    gs://mybucket/mydata.parquet

Perintah berikut memuat data dari gs://mybucket/mydata.parquet dan menambahkan data ke tabel bernama mytable di mydataset.

    bq load \
    --noreplace \
    --source_format=PARQUET \
    mydataset.mytable \
    gs://mybucket/mydata.parquet

Untuk informasi tentang cara menambahkan dan menimpa tabel berpartisi menggunakan alat command line bq, lihat Menambahkan dan menimpa data tabel berpartisi.

API

1. Buat tugas load yang mengarah ke data sumber di Cloud Storage.

2. (Opsional) Tentukan lokasi Anda di properti location di bagian jobReference pada resource tugas.

3. Properti source URIs harus sepenuhnya memenuhi syarat, dalam format gs://BUCKET/OBJECT. Anda dapat menyertakan beberapa URI sebagai daftar yang dipisahkan koma. Perlu diperhatikan bahwa karakter pengganti juga didukung.

4. Tentukan format data dengan menetapkan properti configuration.load.sourceFormat ke PARQUET.

5. Tentukan preferensi tulis dengan menetapkan properti configuration.load.writeDisposition ke WRITE_TRUNCATE atau WRITE_APPEND.

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 mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

import (
	"context"
	"fmt"

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

// importParquetTruncate demonstrates loading Apache Parquet data from Cloud Storage into a table
// and overwriting/truncating existing data in the table.
func importParquetTruncate(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.parquet")
	gcsRef.SourceFormat = bigquery.Parquet
	gcsRef.AutoDetect = true
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	loader.WriteDisposition = bigquery.WriteTruncate

	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}

	if status.Err() != nil {
		return fmt.Errorf("job completed with error: %v", status.Err())
	}
	return nil
}

Java

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

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui 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.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.JobInfo.WriteDisposition;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.TableId;
import java.math.BigInteger;

public class LoadParquetReplaceTable {

  public static void runLoadParquetReplaceTable() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    loadParquetReplaceTable(datasetName);
  }

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

      // Imports a GCS file into a table and overwrites table data if table already exists.
      // This sample loads CSV file at:
      // https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.csv
      String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.parquet";
      TableId tableId = TableId.of(datasetName, "us_states");

      // For more information on LoadJobConfiguration see:
      // https://googleapis.dev/java/google-cloud-clients/latest/com/google/cloud/bigquery/LoadJobConfiguration.Builder.html
      LoadJobConfiguration configuration =
          LoadJobConfiguration.builder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.parquet())
              // Set the write disposition to overwrite existing table data.
              .setWriteDisposition(WriteDisposition.WRITE_TRUNCATE)
              .build();

      // For more information on Job see:
      // https://googleapis.dev/java/google-cloud-clients/latest/index.html?com/google/cloud/bigquery/package-summary.html
      // Load the table
      Job job = bigquery.create(JobInfo.of(configuration));

      // 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 = job.waitFor();
      if (completedJob == null) {
        System.out.println("Job not executed since it no longer exists.");
        return;
      } else if (completedJob.getStatus().getError() != null) {
        System.out.println(
            "BigQuery was unable to load into the table due to an error: \n"
                + job.getStatus().getError());
        return;
      }

      // Check number of rows loaded into the table
      BigInteger numRows = bigquery.getTable(tableId).getNumRows();
      System.out.printf("Loaded %d rows. \n", numRows);

      System.out.println("GCS parquet overwrote existing table successfully.");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Table extraction job was interrupted. \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 mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

// Instantiate clients
const bigquery = new BigQuery();
const storage = new Storage();

/**
 * This sample loads the CSV file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.csv
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.parquet';

async function loadParquetFromGCSTruncate() {
  /**
   * Imports a GCS file into a table and overwrites
   * table data if table already exists.
   */

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

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const metadata = {
    sourceFormat: 'PARQUET',
    // Set the write disposition to overwrite existing table data.
    writeDisposition: 'WRITE_TRUNCATE',
    location: 'US',
  };

  // Load data from a Google Cloud Storage file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(storage.bucket(bucketName).file(filename), metadata);
  // load() waits for the job to finish
  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;
  }
}

PHP

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

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

use Google\Cloud\BigQuery\BigQueryClient;
use Google\Cloud\Core\ExponentialBackoff;

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $datasetId = 'The BigQuery dataset ID';
// $tableID = 'The BigQuery table ID';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$table = $bigQuery->dataset($datasetId)->table($tableId);

// create the import job
$gcsUri = 'gs://cloud-samples-data/bigquery/us-states/us-states.parquet';
$loadConfig = $table->loadFromStorage($gcsUri)->sourceFormat('PARQUET')->writeDisposition('WRITE_TRUNCATE');
$job = $table->runJob($loadConfig);

// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    print('Waiting for job to complete' . PHP_EOL);
    $job->reload();
    if (!$job->isComplete()) {
        throw new Exception('Job has not yet completed', 500);
    }
});

// check if the job has errors
if (isset($job->info()['status']['errorResult'])) {
    $error = $job->info()['status']['errorResult']['message'];
    printf('Error running job: %s' . PHP_EOL, $error);
} else {
    print('Data imported successfully' . PHP_EOL);
}

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 mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Untuk mengganti baris dalam tabel yang ada, tetapkan properti LoadJobConfig.write_disposition ke WRITE_TRUNCATE.

import io

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

body = io.BytesIO(b"Washington,WA")
client.load_table_from_file(body, table_id, job_config=job_config).result()
previous_rows = client.get_table(table_id).num_rows
assert previous_rows > 0

job_config = bigquery.LoadJobConfig(
    write_disposition=bigquery.WriteDisposition.WRITE_TRUNCATE,
    source_format=bigquery.SourceFormat.PARQUET,
)

uri = "gs://cloud-samples-data/bigquery/us-states/us-states.parquet"
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)
print("Loaded {} rows.".format(destination_table.num_rows))

Memuat data Parquet berpartisi hive

BigQuery mendukung pemuatan data Parquet berpartisi hive yang disimpan di Cloud Storage dan mengisi kolom partisi hive sebagai kolom di tabel terkelola BigQuery tujuan. Untuk informasi selengkapnya, lihat Memuat data yang dipartisi secara eksternal.

Konversi Parquet

Bagian ini menjelaskan cara BigQuery mengurai berbagai jenis data saat memuat data Parquet.

Beberapa jenis data Parquet (seperti INT32, INT64, BYTE_ARRAY, dan FIXED_LEN_BYTE_ARRAY) dapat dikonversi menjadi beberapa jenis data BigQuery. Untuk memastikan BigQuery mengonversi jenis data Parquet dengan benar, tentukan jenis data yang sesuai di file Parquet.

Misalnya, untuk mengonversi jenis data INT32 Parquet ke jenis data DATE BigQuery, tentukan hal berikut:

optional int32 date_col (DATE);

BigQuery mengonversi jenis data Parquet menjadi jenis data BigQuery yang dijelaskan di bagian berikut.

Konversi jenis

Jenis Parquet	Jenis logika Parquet	Jenis data BigQuery
BOOLEAN	Tidak ada	BOOLEAN
INT32	Tidak ada, INTEGER (UINT_8, UINT_16, UINT_32, INT_8, INT_16, INT_32)	INT64
INT32	DECIMAL	NUMERIC, BIGNUMERIC, atau STRING
INT32	DATE	DATE
INT64	Tidak ada, INTEGER (UINT_64, INT_64)	INT64
INT64	DECIMAL	NUMERIC, BIGNUMERIC, atau STRING
INT64	TIMESTAMP, precision=MILLIS (TIMESTAMP_MILLIS)	TIMESTAMP
INT64	TIMESTAMP, precision=MICROS (TIMESTAMP_MICROS)	TIMESTAMP
INT96	Tidak ada	TIMESTAMP
FLOAT	Tidak ada	FLOAT64
DOUBLE	Tidak ada	FLOAT64
BYTE_ARRAY	Tidak ada	BYTES
BYTE_ARRAY	STRING (UTF8)	STRING
FIXED_LEN_BYTE_ARRAY	DECIMAL	NUMERIC, BIGNUMERIC, atau STRING
FIXED_LEN_BYTE_ARRAY	Tidak ada	BYTES

Grup bertingkat dikonversi menjadi jenis STRUCT. Kombinasi lain dari jenis Parquet dan jenis yang dikonversi tidak didukung.

Jenis logika yang tidak ditandatangani

Jenis Parquet UINT_8, UINT_16, UINT_32, dan UINT_64 tidak ditandatangani. BigQuery akan memperlakukan nilai-nilai dengan jenis ini sebagai tidak ditandatangani saat memuat ke kolom INTEGER yang ditandatangani BigQuery. Dalam kasus UINT_64, error akan ditampilkan jika nilai yang tidak ditandatangani melebihi nilai INTEGER maksimum 9.223.372.036.854.775.807.

Jenis logika decimal (desimal)

Jenis logika Decimal dapat dikonversi menjadi jenis NUMERIC, BIGNUMERIC, atau STRING. Jenis yang dikonversi bergantung pada parameter presisi dan skala dari jenis logika decimal dan jenis target desimal yang ditentukan. Tentukan jenis target desimal sebagai berikut:

• Untuk tugas pemuatan menggunakan jobs.insert API: gunakan kolom JobConfigurationLoad.decimalTargetTypes.
• Untuk tugas pemuatan menggunakan perintah bq load pada alat command line bq: gunakan flag --decimal_target_types.
• Untuk kueri terhadap tabel dengan sumber eksternal: gunakan kolom ExternalDataConfiguration.decimalTargetTypes.
• Untuk tabel eksternal persisten yang dibuat dengan DDL: gunakan opsi decimal_target_types.

Jenis logika enum

Jenis logika Enum dapat dikonversi menjadi STRING atau BYTES. Tentukan jenis target yang dikonversi sebagai berikut:

• Untuk tugas pemuatan menggunakan jobs.insert API: gunakan kolom JobConfigurationLoad.parquetOptions.
• Untuk tugas pemuatan menggunakan perintah bq load pada alat command line bq: gunakan flag --parquet_enum_as_string.
• Untuk tabel eksternal persisten yang dibuat dengan bq mk: gunakan flag --parquet_enum_as_string.

Jenis logika daftar

Anda dapat mengaktifkan inferensi skema untuk jenis logika LIST Parquet. BigQuery memeriksa apakah node LIST berada dalam bentuk standar atau dalam salah satu bentuk yang dijelaskan oleh aturan kompatibilitas mundur:

// standard form
<optional | required> group <name> (LIST) {
  repeated group list {
    <optional | required> <element-type> element;
  }
}

Jika ya, kolom yang sesuai untuk node LIST dalam skema yang dikonversi akan diperlakukan seolah-olah node memiliki skema berikut:

repeated <element-type> <name>

"Daftar" dan "elemen" node dihilangkan.

• Untuk tugas pemuatan menggunakan jobs.insert API: gunakan kolom JobConfigurationLoad.parquetOptions.
• Untuk tugas pemuatan menggunakan perintah bq load pada alat command line bq: gunakan flag --parquet_enable_list_inference.
• Untuk tabel eksternal persisten yang dibuat dengan bq mk: gunakan flag --parquet_enable_list_inference.

Data geospasial

Anda dapat memuat file parquet yang berisi WKT, WKB berenkode heksadesimal, atau GeoJSON dalam kolom STRING, atau WKB di kolom BYTE_ARRAY dengan menentukan skema BigQuery dengan jenis GEOGRAPHY. Lihat Memuat Data Geospasial.

Catatan: Berhati-hatilah saat menggunakan pendekatan ini untuk data GeoParquet. BigQuery tidak akan membaca metadata tentang sistem koordinat dan orientasi poligon.

Konversi 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 nama kolom yang fleksibel, BigQuery mendukung awal nama kolom dengan angka. Berhati-hatilah saat memulai kolom dengan angka, karena penggunaan nama kolom yang fleksibel 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 fleksibel.

Nama kolom memiliki panjang maksimum 300 karakter. Nama kolom tidak boleh menggunakan awalan berikut:

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

Nama kolom duplikat tidak diizinkan meskipun kasusnya berbeda. Misalnya, kolom bernama Column1 dianggap identik dengan kolom bernama column1. Untuk mempelajari aturan penamaan kolom lebih lanjut, lihat Nama kolom dalam referensi GoogleSQL.

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

• Hindari penggunaan nama yang sama untuk tabel dan kolomnya.

• Tetapkan alias yang berbeda pada 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 mereferensikan 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 terkait kolom nama Anda, termasuk akses yang diperluas ke 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 seperti yang diwakili oleh ekspresi reguler Unicode \p{N}.
• Karakter tanda baca konektor apa pun, termasuk garis bawah, seperti yang diwakili 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 seperti yang diwakili oleh ekspresi reguler Unicode \p{M}. Misalnya, aksen, umlaut, atau kotak penutup.
• Karakter khusus berikut:
  • Tanda ampersand (&) sebagaimana diwakili oleh ekspresi reguler Unicode \u0026.
  • Tanda persen (%) sebagaimana diwakili oleh ekspresi reguler Unicode \u0025.
  • Tanda sama dengan (=) sebagaimana diwakili oleh ekspresi reguler Unicode \u003D.
  • Tanda plus (+) sebagaimana diwakili oleh ekspresi reguler Unicode \u002B.
  • Tanda titik dua (:) sebagaimana diwakili oleh ekspresi reguler Unicode \u003A.
  • Tanda apostrof (') sebagaimana diwakili oleh ekspresi reguler Unicode \u0027.
  • Tanda kurang dari (<) sebagaimana diwakili oleh ekspresi reguler Unicode \u003C.
  • Tanda lebih besar dari (>) sebagaimana diwakili oleh ekspresi reguler Unicode \u003E.
  • Tanda pagar (#) sebagaimana diwakili oleh ekspresi reguler Unicode \u0023.
  • Garis vertikal (|) sebagaimana diwakili oleh ekspresi reguler Unicode \u007c.
  • Spasi kosong.

Nama kolom fleksibel tidak mendukung karakter khusus berikut:

• Tanda seru (!) sebagaimana diwakili oleh ekspresi reguler Unicode \u0021.
• Tanda kutip (") sebagaimana diwakili oleh ekspresi reguler Unicode \u0022.
• Tanda dolar ($) sebagaimana diwakili oleh ekspresi reguler Unicode \u0024.
• Tanda kurung buka (() sebagaimana diwakili oleh ekspresi reguler Unicode \u0028.
• Tanda kurung tutup ()) sebagaimana diwakili oleh ekspresi reguler Unicode \u0029.
• Tanda bintang (*) sebagaimana diwakili oleh ekspresi reguler Unicode \u002A.
• Tanda koma (,) sebagaimana diwakili oleh ekspresi reguler Unicode \u002C.
• Tanda titik (.) sebagaimana diwakili oleh ekspresi reguler Unicode \u002E.
• Tanda garis miring (/) sebagaimana diwakili oleh ekspresi reguler Unicode \u002F.
• Tanda titik koma (;) sebagaimana diwakili oleh ekspresi reguler Unicode \u003B.
• Tanda tanya (?) sebagaimana diwakili oleh ekspresi reguler Unicode \u003F.
• Tanda at (@) sebagaimana diwakili oleh ekspresi reguler Unicode \u0040.
• Tanda kurung siku buka ([) sebagaimana diwakili oleh ekspresi reguler Unicode \u005B.
• Tanda garis miring terbalik (\) sebagaimana diwakili oleh ekspresi reguler Unicode \u005C.
• Tanda kurung siku tutup (]) sebagaimana diwakili oleh ekspresi reguler Unicode \u005D.
• Tanda aksen sirkumfleks (^) sebagaimana diwakili oleh ekspresi reguler Unicode \u005E.
• Tanda aksen nontirus (`) sebagaimana diwakili oleh ekspresi reguler Unicode \u0060.
• Tanda kurung kurawal buka {{) sebagaimana diwakili oleh ekspresi reguler Unicode \u007B.
• Tanda kurung kurawal tutup (}) sebagaimana diwakili oleh ekspresi reguler Unicode \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 menetapkan 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 memberikan 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 dalam pratinjau, nama kolom apa pun yang tidak valid (misalnya, kolasi nama kolom) akan menampilkan error. Untuk project yang tidak terdaftar, permintaan pemuatan akan mengganti karakter yang tidak valid dengan garis bawah, alih-alih menampilkan error.
• 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, nama kolom apa pun yang tidak valid (misalnya, kolasi nama kolom) akan menampilkan error. Untuk project yang tidak terdaftar, permintaan pemuatan akan mengganti karakter yang tidak valid dengan garis bawah, alih-alih menampilkan error.

Nama kolom fleksibel tidak didukung dengan tabel eksternal.

Anda tidak dapat memuat file Parquet yang berisi kolom yang memiliki tanda titik (.) pada nama kolom.

Jika nama kolom Parquet berisi karakter lain (selain titik), karakter tersebut akan diganti dengan garis bawah. Anda dapat menambahkan garis bawah ke nama kolom untuk menghindari konflik. Misalnya, jika file Parquet berisi 2 kolom Column1 dan column1, kolom-kolom tersebut akan dimuat sebagai Column1 dan column1_.

Men-debug file Parquet

Jika tugas pemuatan Anda gagal dengan error data, Anda dapat menggunakan PyArrow untuk memverifikasi apakah file data Parquet Anda rusak. Jika PyArrow gagal membaca file, file kemungkinan akan ditolak oleh tugas pemuatan BigQuery. Contoh berikut menunjukkan cara membaca konten file Parquet menggunakan PyArrow:

from pyarrow import parquet as pq

# Read the entire file
pq.read_table('your_sample_file.parquet')
# Read specific columns
pq.read_table('your_sample_file.parquet',columns=['some_column', 'another_column'])
# Read the metadata of specific columns
file_metadata=pq.read_metadata('your_sample_file.parquet')
for col in file_metadata.row_group(0).to_dict()['columns']:
    print col['column_path_in_schema']
    print col['num_values']

Untuk informasi selengkapnya, lihat dokumen PyArrow.