Memuat data ORC dari Cloud Storage

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

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

Saat memuat data ORC dari Cloud Storage, Anda dapat memuat data 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 cara memuat data ORC dari file lokal, lihat Memuat data ke BigQuery dari sumber data 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.

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) pada bucket. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran bawaan ini berisi izin yang diperlukan untuk memuat data dari bucket Cloud Storage. Untuk melihat izin yang benar-benar diperlukan, luaskan 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 bawaan lainnya.

Membuat set data

Membuat set data BigQuery untuk menyimpan data Anda.

Skema ORC

Saat Anda memuat file ORC ke BigQuery, skema tabel diambil secara otomatis dari data sumber deskripsi mandiri. Saat BigQuery mengambil skema dari data sumber, file terakhir menurut abjad akan digunakan.

Misalnya, Anda memiliki file ORC berikut di Cloud Storage:

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

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

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

Saat BigQuery mendeteksi skema, beberapa jenis data ORC akan dikonversi ke jenis data BigQuery agar kompatibel dengan sintaksis GoogleSQL. Semua kolom dalam skema yang terdeteksi adalah NULLABLE. Untuk informasi selengkapnya, lihat Konversi ORC.

Saat Anda memuat beberapa file ORC yang memiliki skema berbeda, kolom identik (dengan nama yang sama dan level bertingkat yang sama) yang ditentukan dalam beberapa skema harus dipetakan ke jenis data BigQuery terkonversi yang sama pada setiap definisi skema.

Untuk memberikan skema tabel guna 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.orc".

Kompresi ORC

BigQuery mendukung codec kompresi berikut untuk konten file ORC:

  • Zlib
  • Snappy
  • LZO
  • LZ4

Data dalam file ORC tidak akan tetap terkompresi setelah diupload ke BigQuery. Penyimpanan data dilaporkan dalam byte logis atau byte fisik, bergantung pada model penagihan penyimpanan set data. Untuk mendapatkan informasi tentang penggunaan penyimpanan, buat kueri tampilan INFORMATION_SCHEMA.TABLE_STORAGE.

Memuat data ORC ke tabel baru

Anda dapat memuat data ORC ke tabel baru dengan:

  • Menggunakan konsol Google Cloud
  • Menggunakan perintah bq load alat command line bq
  • Memanggil metode API jobs.insert dan mengonfigurasi tugas load
  • Menggunakan library klien

Untuk memuat data ORC dari Cloud Storage ke tabel BigQuery 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. pilih file sumber untuk membuat tabel BigQuery
      2. Untuk Format file, pilih ORC.
    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. Skemanya adalah dijelaskan sendiri dalam file ORC.
    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.

SQL

Gunakan pernyataan DDL LOAD DATA. Contoh berikut memuat file ORC 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 = 'ORC',
      uris = ['gs://bucket/path/file.orc']);

  3. Klik Run.

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

bq

Gunakan perintah bq load, tentukan ORC sebagai 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. Menggunakan 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 informasi selengkapnya tentang tabel berpartisi, lihat:

    Untuk informasi selengkapnya tentang tabel yang dikelompokkan, lihat:

    Untuk mengetahui informasi selengkapnya tentang enkripsi tabel, lihat:

Untuk memuat data ORC ke BigQuery, masukkan perintah berikut:

bq --location=location load \
--source_format=format \
dataset.table \
path_to_source

Dengan keterangan:

  • location adalah lokasi Anda. Flag --location bersifat opsional. Misalnya, jika menggunakan BigQuery di wilayah Tokyo, Anda dapat menetapkan nilai flag ke asia-northeast1. Anda dapat menetapkan nilai default untuk lokasi menggunakan file .bigqueryrc.
  • format adalah ORC.
  • dataset adalah set data yang sudah ada.
  • table adalah nama tabel tempat Anda memuat data.
  • path_to_source adalah 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.orc ke tabel bernama mytable di mydataset.

    bq load \
    --source_format=ORC \
    mydataset.mytable \
    gs://mybucket/mydata.orc

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

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

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

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

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=ORC \
    mydataset.mytable \
    gs://mybucket/mydata*.orc

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 --autodetect \
    --source_format=ORC \
    mydataset.mytable \
    "gs://mybucket/00/*.orc","gs://mybucket/01/*.orc"

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 ORC dengan menetapkan properti sourceFormat ke ORC.

  5. Untuk memeriksa status tugas, panggil jobs.get(job_id*), dengan job_id yang merupakan 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 datanya 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 pekerjaan tertentu bersifat idempoten. Anda dapat mencoba sebanyak yang Anda inginkan pada ID pekerjaan yang sama, dan maksimal satu dari operasi tersebut berhasil.

C#

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 BigQueryLoadTableGcsOrc
{
    public void LoadTableGcsOrc(
        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.orc";
        var dataset = client.GetDataset(datasetId);
        TableReference destinationTableRef = dataset.GetTableReference(
            tableId: "us_states");
        // Create job configuration
        var jobOptions = new CreateLoadJobOptions()
        {
            SourceFormat = FileFormat.Orc
        };
        // Create and run job
        var loadJob = client.CreateLoadJob(
            sourceUri: gcsURI,
            destination: destinationTableRef,
            // Pass null as the schema because the schema is inferred when
            // loading Orc data
            schema: null,
            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}");
    }
}

Go

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

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

import (
	"context"
	"fmt"

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

// importORCTruncate demonstrates loading Apache ORC data from Cloud Storage into a table.
func importORC(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.orc")
	gcsRef.SourceFormat = bigquery.ORC
	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

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 ORC data from Cloud Storage into a new BigQuery table
public class LoadOrcFromGCS {

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

  public static void loadOrcFromGCS(
      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, FormatOptions.orc())
              .setSchema(schema)
              .build();

      // Load data from a GCS ORC 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() && job.getStatus().getError() == null) {
        System.out.println("ORC from GCS successfully added during load append job");
      } else {
        System.out.println(
            "BigQuery was unable to load into the table due to an error:"
                + job.getStatus().getError());
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

Node.js

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

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

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

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

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

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

  /**
   * TODO(developer): Uncomment the following line 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: 'ORC',
    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 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.orc';
$loadConfig = $table->loadFromStorage($gcsUri)->sourceFormat('ORC');
$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 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(source_format=bigquery.SourceFormat.ORC)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.orc"

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

Ruby

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

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

require "google/cloud/bigquery"

def load_table_gcs_orc dataset_id = "your_dataset_id"
  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  gcs_uri  = "gs://cloud-samples-data/bigquery/us-states/us-states.orc"
  table_id = "us_states"

  load_job = dataset.load_job table_id, gcs_uri, format: "orc"
  puts "Starting job #{load_job.job_id}"

  load_job.wait_until_done! # Waits for table load to complete.
  puts "Job finished."

  table = dataset.table table_id
  puts "Loaded #{table.rows_count} rows to table #{table.id}"
end

Menambahkan atau menimpa tabel dengan data ORC

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, keamanan tingkat baris, dan menghapus semua kunci Cloud KMS.

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

Anda dapat menambahkan atau menimpa tabel dengan:

  • Menggunakan konsol Google Cloud
  • Menggunakan perintah bq load alat command line bq
  • Memanggil metode API jobs.insert dan mengonfigurasi tugas load
  • Menggunakan library klien

Untuk menambahkan atau menimpa tabel dengan data ORC:

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. pilih file sumber untuk membuat tabel BigQuery
      2. Untuk Format file, pilih ORC.
    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. Skemanya adalah dijelaskan sendiri dalam file ORC.
    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 ORC 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 = 'ORC',
      uris = ['gs://bucket/path/file.orc']);

  3. Klik Run.

Untuk mengetahui 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 ORC. Karena skema ORC otomatis diambil dari data sumber deskripsi mandiri, Anda tidak perlu memberikan definisi skema.

(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

Dengan keterangan:

  • location adalah lokasi Anda. Flag --location bersifat opsional. Anda dapat menetapkan nilai default untuk lokasi menggunakan file .bigqueryrc.
  • format adalah ORC.
  • dataset adalah set data yang sudah ada.
  • table adalah nama tabel tempat Anda memuat data.
  • path_to_source adalah 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.orc dan menimpa tabel bernama mytable di mydataset.

    bq load \
    --replace \
    --source_format=ORC \
    mydataset.mytable \
    gs://mybucket/mydata.orc

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

    bq load \
    --noreplace \
    --source_format=ORC \
    mydataset.mytable \
    gs://mybucket/mydata.orc

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

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

C#

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 BigQueryLoadTableGcsOrcTruncate
{
    public void LoadTableGcsOrcTruncate(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id",
        string tableId = "your_table_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var gcsURI = "gs://cloud-samples-data/bigquery/us-states/us-states.orc";
        var dataset = client.GetDataset(datasetId);
        TableReference destinationTableRef = dataset.GetTableReference(
            tableId: "us_states");
        // Create job configuration
        var jobOptions = new CreateLoadJobOptions()
        {
            SourceFormat = FileFormat.Orc,
            WriteDisposition = WriteDisposition.WriteTruncate
        };
        // Create and run job
        var loadJob = client.CreateLoadJob(
            sourceUri: gcsURI,
            destination: destinationTableRef,
            // Pass null as the schema because the schema is inferred when
            // loading Orc data
            schema: null, 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}");
    }
}

Go

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

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

import (
	"context"
	"fmt"

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

// importORCTruncate demonstrates loading Apache ORC data from Cloud Storage into a table
// and overwriting/truncating existing data in the table.
func importORCTruncate(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.orc")
	gcsRef.SourceFormat = bigquery.ORC
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	// Default for import jobs is to append data to a table.  WriteTruncate
	// specifies that existing data should instead be replaced/overwritten.
	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

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;

// Sample to overwrite the BigQuery table data by loading a ORC file from GCS
public class LoadOrcFromGcsTruncate {

  public static void runLoadOrcFromGcsTruncate() {
    // 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.orc";
    loadOrcFromGcsTruncate(datasetName, tableName, sourceUri);
  }

  public static void loadOrcFromGcsTruncate(
      String datasetName, String tableName, String sourceUri) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.newBuilder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.orc())
              // Set the write disposition to overwrite existing table data
              .setWriteDisposition(JobInfo.WriteDisposition.WRITE_TRUNCATE)
              .build();

      // Load data from a GCS ORC 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() && job.getStatus().getError() == null) {
        System.out.println("Table is successfully overwritten by ORC file loaded from GCS");
      } else {
        System.out.println(
            "BigQuery was unable to load into the table due to an error:"
                + job.getStatus().getError());
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

Node.js

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

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

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

// Instantiate the 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.orc';

async function loadORCFromGCSTruncate() {
  /**
   * 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: 'ORC',
    // 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 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.orc';
$loadConfig = $table->loadFromStorage($gcsUri)->sourceFormat('ORC')->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 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.ORC,
)

uri = "gs://cloud-samples-data/bigquery/us-states/us-states.orc"
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))

Ruby

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

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

require "google/cloud/bigquery"

def load_table_gcs_orc_truncate dataset_id = "your_dataset_id",
                                table_id   = "your_table_id"

  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  gcs_uri  = "gs://cloud-samples-data/bigquery/us-states/us-states.orc"

  load_job = dataset.load_job table_id,
                              gcs_uri,
                              format: "orc",
                              write:  "truncate"
  puts "Starting job #{load_job.job_id}"

  load_job.wait_until_done! # Waits for table load to complete.
  puts "Job finished."

  table = dataset.table table_id
  puts "Loaded #{table.rows_count} rows to table #{table.id}"
end

Memuat data ORC yang dipartisi hive

BigQuery mendukung pemuatan data ORC yang dipartisi hive yang disimpan di Cloud Storage dan mengisi kolom partisi hive sebagai kolom di tabel terkelola BigQuery tujuan. Untuk informasi selengkapnya, baca Memuat Data yang Dipartisi secara Eksternal dari Cloud Storage.

Konversi ORC

BigQuery mengonversi jenis data ORC ke jenis data BigQuery berikut:

Jenis primitif

Jenis data ORC Jenis data BigQuery Catatan
boolean BOOLEAN
byte INTEGER
short INTEGER
int INTEGER
long INTEGER
float FLOAT
double FLOAT
string STRING Khusus UTF-8
varchar STRING Khusus UTF-8
char STRING Khusus UTF-8
binary BYTES
date DATE Percobaan untuk mengonversi nilai apa pun dalam data ORC yang kurang dari -719162 hari atau lebih besar dari 2932896 hari akan menampilkan error invalid date value. Jika hal ini memengaruhi Anda, hubungi Dukungan agar nilai yang tidak didukung dikonversi ke nilai minimum BigQuery 0001-01-01 atau nilai maksimum 9999-12-31, sebagaimana mestinya.
timestamp TIMESTAMP

ORC mendukung presisi nanodetik, tetapi BigQuery mengonversi nilai sub-mikrodetik menjadi mikrodetik saat data dibaca.

Percobaan untuk mengonversi nilai apa pun dalam data ORC yang kurang dari -719162 hari atau lebih besar dari 2932896 hari akan menampilkan error invalid date value. Jika hal ini memengaruhi Anda, hubungi Dukungan agar nilai yang tidak didukung dikonversi ke nilai minimum BigQuery 0001-01-01 atau nilai maksimum 9999-12-31, sebagaimana mestinya.

decimal NUMERIC, BIGNUMERIC, atau STRING Lihat Jenis desimal.

Jenis 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:

Jenis kompleks

Jenis data ORC Jenis data BigQuery Catatan
struct RECORD
  • Semua kolom NULLABLE.
  • Urutan kolom diabaikan.
  • Nama kolom harus berupa nama kolom yang valid.
map<K,V> RECORD Kolom map<K,V> ORC dikonversi menjadi RECORD berulang yang berisi dua kolom: kunci dari jenis data yang sama seperti K, dan nilai dari jenis data yang sama seperti V. Kedua kolom NULLABLE.
list kolom berulang Daftar bertingkat dan daftar peta tidak didukung.
union RECORD
  • Jika union hanya memiliki satu varian, union akan dikonversi menjadi kolom NULLABLE.
  • Jika tidak, union akan dikonversi menjadi RECORD dengan daftar kolom NULLABLE. Kolom NULLABLE memiliki akhiran seperti field_0, field_1, dan seterusnya. Hanya salah satu dari kolom tersebut yang diberi nilai saat data dibaca.

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 di GoogleSQL.

Jika nama tabel (misalnya, test) sama dengan salah satu nama kolomnya (misalnya, test), ekspresi SELECT akan 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

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 seperti yang 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 (>) sebagaimana diwakili oleh ekspresi reguler Unicode \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.
  • Tanda koma (,) sebagaimana diwakili oleh ekspresi reguler Unicode \u002C.
  • Titik (.) sebagaimana diwakili oleh reguler Unicode ekspresi \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 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 dalam pratinjau, nama kolom apa pun yang tidak valid (misalnya, kolasi nama kolom) akan menampilkan error. 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.

NULL nilai

Perhatikan bahwa untuk tugas pemuatan, BigQuery mengabaikan elemen NULL untuk jenis gabungan list, karena jika tidak, elemen tersebut akan diterjemahkan ke elemen NULL ARRAY yang tidak dapat dipertahankan ke tabel (lihat Jenis Data untuk mengetahui detailnya).

Untuk informasi selengkapnya tentang jenis data ORC, lihat Spesifikasi Apache ORC™ v1.