Memuat data Avro dari Cloud Storage

Avro adalah format data open source yang memaketkan data serial dengan skema data dalam file yang sama.

Saat memuat data Avro 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 format 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 mengetahui informasi tentang cara memuat data Avro dari file lokal, lihat Memuat data ke BigQuery dari sumber data lokal.

Catatan: BigQuery tidak mendukung pemuatan file skema Avro (.avsc) mandiri. Untuk mengimpor skema ke BigQuery, lihat Menentukan file skema JSON.

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 Cloud Storage URI, tugas pemuatan akan gagal.

Persyaratan file input

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

• Batasi ukuran baris maksimal 50 MB.
• Jika baris berisi banyak kolom array, atau kolom array yang sangat panjang, bagi nilai array tersebut menjadi kolom terpisah.

Sebelum memulai

Berikan peran Identity and Access Management (IAM) yang memberi pengguna izin yang diperlukan untuk melakukan setiap tugas dalam dokumen ini, serta buat set data dan tabel 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 Anda 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 ditentukan 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 yang telah ditetapkan lainnya.

Membuat set data dan tabel

Untuk menyimpan data, Anda harus membuat set data BigQuery, lalu membuat tabel BigQuery di dalam set data tersebut.

Manfaat Avro

Avro adalah format pilihan untuk memuat data ke BigQuery. Pemuatan file Avro memiliki keunggulan berikut dibandingkan CSV dan JSON (dibatasi newline):

• Format biner Avro:
  • Lebih cepat dimuat. Data dapat dibaca secara paralel, meskipun blok data dikompresi.
  • Tidak memerlukan pengetikan atau serialisasi.
  • Lebih mudah diurai karena tidak ditemukan masalah encoding dalam format lain seperti ASCII.
• Saat Anda memuat file Avro ke BigQuery, skema tabel otomatis diambil dari data sumber yang mendeskripsikan formatnya sendiri.

Skema Avro

Saat Anda memuat file Avro ke dalam tabel BigQuery baru, skema tabel otomatis diambil menggunakan data sumber. Saat BigQuery mengambil skema dari data sumber, file terakhir menurut abjad akan digunakan.

Misalnya, Anda memiliki file Avro berikut di Cloud Storage:

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

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

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

Saat mengimpor beberapa file Avro dengan berbagai skema Avro, semua skema harus kompatibel dengan resolusi skema Avro.

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

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.avro".

Kompresi Avro

BigQuery mendukung codec kompresi berikut untuk konten file Avro:

• Snappy
• DEFLATE

Memuat data Avro ke dalam tabel baru

Untuk memuat data Avro dari Cloud Storage ke dalam tabel BigQuery baru, pilih salah satu opsi berikut:

Konsol

1. Di konsol Google Cloud, buka halaman BigQuery.

   Buka BigQuery

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

3. Luaskan opsi Actions dan klik Open.

4. Di panel detail, klik Create table .

5. Di halaman Create table, di bagian Source:

   • Untuk Create table from, pilih Google Cloud Storage.

   • Di kolom sumber, cari atau masukkan Cloud Storage URI. Perhatikan bahwa Anda tidak dapat menyertakan beberapa URI di Konsol Google Cloud, tetapi karakter pengganti didukung. Bucket Cloud Storage harus berada di lokasi yang sama dengan set data yang berisi tabel yang Anda buat.

     

   • Untuk File format, pilih Avro.

6. Di halaman Create table, di bagian Destination:

   • Untuk Dataset name, pilih set data yang sesuai.
   • Pastikan Table type ditetapkan ke Native table.
   • Pada kolom Table name, masukkan nama tabel yang Anda buat di BigQuery.

7. Di bagian Schema, Anda tidak perlu melakukan tindakan apa pun. Skema ini dijelaskan sendiri dalam file Avro.

8. (Opsional) Untuk mempartisi tabel, pilih opsi Anda di Partition and cluster settings. Untuk mengetahui informasi selengkapnya, lihat Membuat tabel berpartisi.

9. (Opsional) Untuk Partitioning filter, klik kotak Require partition filter untuk mengharuskan pengguna menyertakan klausa WHERE yang menentukan partisi yang akan dikueri. Mengharuskan penggunaan filter partisi dapat mengurangi biaya dan meningkatkan performa. Untuk mengetahui informasi selengkapnya, lihat Membuat kueri tabel berpartisi. Opsi ini tidak tersedia jika No partitioning dipilih.

10. (Opsional) Untuk mengelompokkan tabel, di kotak Clustering order, masukkan antara satu dan empat nama kolom.

11. (Opsional) Klik Advanced options.

    • Untuk Write preferences, tetap pilih Write if empty. Opsi ini akan membuat tabel baru dan memuat data Anda ke dalamnya.
    • Untuk Unknown values, biarkan opsi Ignore unknown values kosong. Opsi ini hanya berlaku untuk file CSV dan JSON.
    • 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.

12. Klik Buat tabel.

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

Setelah tabel dibuat, Anda dapat memperbarui akhir masa berlaku, deskripsi, dan label tabel, tetapi Anda tidak dapat menambahkan 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 Avro ke dalam 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 = 'avro',
     uris = ['gs://bucket/path/file.avro']);
   

3. Klik Run.

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

bq

Gunakan perintah bq load, tentukan AVRO 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. Mengharuskan penggunaan 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 Avro ke BigQuery, masukkan perintah berikut:

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

Ganti kode berikut:

• location adalah 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 sebesar AVRO.
• 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.avro ke dalam tabel bernama mytable di mydataset.

    bq load \
    --source_format=AVRO \
    mydataset.mytable \
    gs://mybucket/mydata.avro

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

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

Perintah berikut memuat data dari gs://mybucket/mydata.avro ke dalam tabel berpartisi baru bernama mytable di mydataset. Tabel dipartisi pada kolom mytimestamp.

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

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

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=AVRO \
    mydataset.mytable \
    "gs://mybucket/00/*.avro","gs://mybucket/01/*.avro"

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

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

   • Jika statusnya status.state = DONE, tugas berhasil diselesaikan.
   • Jika properti status.errorResult ada, permintaan gagal, dan objek tersebut akan menyertakan informasi yang menjelaskan penyebabnya. 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 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

import (
	"context"
	"fmt"

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

// importAvro demonstrates loading Apache Avro data from Cloud Storage into a table.
func importAvro(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.avro")
	gcsRef.SourceFormat = bigquery.Avro
	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.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 load Avro data from Cloud Storage into a new BigQuery table
public class LoadAvroFromGCS {

  public static void runLoadAvroFromGCS() {
    // 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.avro";
    loadAvroFromGCS(datasetName, tableName, sourceUri);
  }

  public static void loadAvroFromGCS(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.of(tableId, sourceUri, FormatOptions.avro());

      // Load data from a GCS Avro file into the table
      Job job = bigquery.create(JobInfo.of(loadConfig));
      // Blocks until this load table job completes its execution, either failing or succeeding.
      job = job.waitFor();
      if (job.isDone()) {
        System.out.println("Avro from GCS successfully loaded in a table");
      } else {
        System.out.println(
            "BigQuery was unable to load into the table due to an error:"
                + job.getStatus().getError());
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

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 Avro file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.avro
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.avro';

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

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

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

  // 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), jobConfigurationLoad);

  // 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;
  }
}

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.

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

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

Mengekstrak data JSON dari data Avro

Ada dua cara untuk memastikan bahwa data Avro dimuat ke BigQuery sebagai data JSON:

1. Anotasikan skema Avro Anda dengan sqlType yang ditetapkan ke JSON. Misalnya, jika Anda memuat data dengan skema Avro berikut, kolom json_field akan dibaca sebagai jenis JSON:

   {
       "type": {"type": "string", "sqlType": "JSON"},
       "name": "json_field"
   }
   

2. Tentukan skema tabel tujuan BigQuery secara eksplisit dan tetapkan jenis kolom ke JSON. Untuk mengetahui informasi selengkapnya, lihat Menentukan skema.

Jika Anda tidak menentukan JSON sebagai jenis dalam skema Avro atau skema tabel BigQuery, data akan dibaca sebagai STRING.

Menambahkan atau menimpakan data Avro ke tabel

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.

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

Untuk menambahkan atau menimpakan data Avro ke tabel:

Konsol

1. Di konsol Google Cloud, buka halaman BigQuery.

   Buka BigQuery

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

3. Luaskan opsi Actions dan klik Open.

4. Di panel detail, klik Create table .

5. Di halaman Create table, di bagian Source:

   • Untuk Create table from, pilih Cloud Storage.

   • Di kolom sumber, jelajahi atau masukkan Cloud Storage URI. Perlu diperhatikan bahwa Anda tidak dapat menyertakan beberapa URI di Konsol Google Cloud, tetapi karakter pengganti didukung. Bucket Cloud Storage harus berada di lokasi yang sama dengan set data yang berisi tabel yang Anda tambahkan atau timpa.

     

   • Untuk File format, pilih Avro.

6. Di halaman Create table, di bagian Destination:

   • Untuk Dataset name, pilih set data yang sesuai.

     

   • Di kolom Table name, masukkan nama tabel yang Anda tambahkan atau timpa di BigQuery.

   • Pastikan Table type ditetapkan ke Native table.

7. Di bagian Schema, Anda tidak perlu melakukan tindakan apa pun. Skema ini dijelaskan sendiri dalam file Avro.

   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.

8. Untuk Partition and cluster settings, gunakan nilai default. Anda tidak dapat mengonversi tabel menjadi tabel berpartisi atau tabel yang dikelompokkan dengan menambahkan data atau menimpanya. Konsol Google Cloud tidak mendukung penambahan data ke atau penimpaan tabel berdipartisi atau tabel yang dikelompokkan dalam tugas pemuatan.

9. Klik Advanced options.

   • Untuk Write preference, pilih Append to table atau Overwrite table.
   • Untuk Unknown values, biarkan opsi Ignore unknown values kosong. Opsi ini hanya berlaku untuk file CSV dan JSON.
   • 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.

10. Klik Buat tabel.

SQL

Gunakan pernyataan DDL LOAD DATA. Contoh berikut menambahkan file Avro ke dalam 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 = 'avro',
     uris = ['gs://bucket/path/file.avro']);
   

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 AVRO. Karena skema Avro otomatis diambil dari data sumber yang mendeskripsikan formatnya 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 adalah lokasi Anda. Flag --location bersifat opsional. Anda dapat menetapkan nilai default untuk lokasi menggunakan file .bigqueryrc.
• format sebesar AVRO.
• 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.avro dan menimpa tabel bernama mytable di mydataset.

    bq load \
    --replace \
    --source_format=AVRO \
    mydataset.mytable \
    gs://mybucket/mydata.avro

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

    bq load \
    --noreplace \
    --source_format=AVRO \
    mydataset.mytable \
    gs://mybucket/mydata.avro

Untuk mengetahui 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 AVRO.

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

Go

import (
	"context"
	"fmt"

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

// importAvroTruncate demonstrates loading Apache Avro data from Cloud Storage into a table
// and overwriting/truncating existing data in the table.
func importAvroTruncate(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.avro")
	gcsRef.SourceFormat = bigquery.Avro
	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 AVRO file from GCS
public class LoadAvroFromGCSTruncate {

  public static void runLoadAvroFromGCSTruncate() {
    // 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.avro";
    loadAvroFromGCSTruncate(datasetName, tableName, sourceUri);
  }

  public static void loadAvroFromGCSTruncate(
      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.avro())
              // Set the write disposition to overwrite existing table data
              .setWriteDisposition(JobInfo.WriteDisposition.WRITE_TRUNCATE)
              .build();

      // Load data from a GCS Avro file into the table
      Job job = bigquery.create(JobInfo.of(loadConfig));
      // Blocks until this load table job completes its execution, either failing or succeeding.
      job = job.waitFor();
      if (job.isDone()) {
        System.out.println("Table is successfully overwritten by AVRO 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 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 Avro file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.avro
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.avro';

async function loadTableGCSAvroTruncate() {
  /**
   * 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 = 'us_states';

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

  // 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), jobConfigurationLoad);

  // 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;
  }
}

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.

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.AVRO,
)

uri = "gs://cloud-samples-data/bigquery/us-states/us-states.avro"
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 Avro yang dipartisi hive

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

Konversi Avro

BigQuery mengonversi jenis data Avro ke jenis data BigQuery berikut:

Jenis primitif

Jenis data Avro tanpa atribut logicalType	Jenis data BigQuery	Notes
null	BigQuery mengabaikan nilai ini
boolean	BOOLEAN
int	INTEGER
long	INTEGER
float	FLOAT
double	FLOAT
byte	BYTES
string	STRING	Khusus UTF-8

Jenis logika

Secara default, BigQuery mengabaikan atribut logicalType untuk sebagian besar jenis dan menggunakan jenis Avro yang mendasarinya. Untuk mengonversi jenis logika Avro ke jenis data BigQuery yang sesuai, tetapkan flag --use_avro_logical_types ke true menggunakan alat command line bq, atau tetapkan properti useAvroLogicalTypes di resource tugas saat Anda memanggil metode jobs.insert untuk membuat tugas pemuatan.

Tabel di bawah menampilkan konversi jenis logika Avro ke jenis data BigQuery.

Jenis logika Avro	Jenis data BigQuery: Jenis logika dinonaktifkan	Jenis data BigQuery: Jenis logika diaktifkan
tanggal	INTEGER	DATE
time-millis	INTEGER	WAKTU
time-micros	INTEGER (dikonversi dari LONG)	WAKTU
timestamp-millis	INTEGER (dikonversi dari LONG)	TIMESTAMP
timestamp-micros	INTEGER (dikonversi dari LONG)	TIMESTAMP
local-timestamp-millis	INTEGER (dikonversi dari LONG)	DATETIME
local-timestamp-micros	INTEGER (dikonversi dari LONG)	DATETIME
durasi	BYTES (dikonversi dari jenis fixed ukuran 12)	BYTES (dikonversi dari jenis fixed ukuran 12)
decimal	NUMERIC, BIGNUMERIC, atau STRING (lihat Jenis logika decimal (desimal))	NUMERIC, BIGNUMERIC, atau STRING (lihat Jenis logika decimal (desimal))

Untuk mengetahui informasi selengkapnya tentang jenis data Avro, lihat Spesifikasi Apache Avro™ 1.8.2.

Catatan: Saat mengekspor ke Avro dari BigQuery, DATETIME diekspor sebagai STRING dengan waktu logika khusus yang tidak dikenali sebagai DATETIME setelah mengimpor kembali ke BigQuery.

Jenis logika date (tanggal)

Pada file Avro yang ingin dimuat, Anda harus menentukan jenis logika date (tanggal) dalam format berikut:

{
       "type": {"logicalType": "date", "type": "int"},
       "name": "date_field"
}

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.

Untuk kompatibilitas mundur, jika jenis target desimal tidak ditentukan, Anda dapat memuat file Avro yang berisi kolom bytes dengan jenis logika decimal ke dalam kolom BYTES pada tabel sementara. Dalam hal ini, jenis logika decimal pada kolom dalam file Avro akan diabaikan. Mode konversi ini tidak digunakan lagi dan mungkin akan dihapus pada masa mendatang.

Untuk mengetahui informasi selengkapnya tentang jenis logika decimal, lihat Spesifikasi Apache Avro™ 1.8.2 Specification.

Jenis logika time (waktu)

Pada file Avro yang ingin dimuat, Anda harus menentukan jenis logika time (waktu) dalam salah satu format berikut.

Untuk presisi milidetik:

{
       "type": {"logicalType": "time-millis", "type": "int"},
       "name": "time_millis_field"
}

Untuk presisi mikrodetik:

{
       "type": {"logicalType": "time-micros", "type": "int"},
       "name": "time_micros_field"
}

Jenis logika timestamp (stempel waktu)

Pada file Avro yang ingin dimuat, Anda harus menentukan jenis logika timestamp (stempel waktu) dalam salah satu format berikut.

Untuk presisi milidetik:

{
       "type": {"logicalType": "timestamp-millis", "type": "long"},
       "name": "timestamp_millis_field"
}

Untuk presisi mikrodetik:

{
       "type": {"logicalType": "timestamp-micros", "type": "long"},
       "name": "timestamp_micros_field"
}

Jenis logika local-timestamp (stempel waktu lokal)

Dalam file Avro yang ingin dimuat, Anda harus menentukan jenis logika local-timestamp (stempel waktu lokal) dalam salah satu format berikut.

Untuk presisi milidetik:

{
       "type": {"logicalType": "local-timestamp-millis", "type": "long"},
       "name": "local_timestamp_millis_field"
}

Untuk presisi mikrodetik:

{
       "type": {"logicalType": "local-timestamp-micros", "type": "long"},
       "name": "local_timestamp_micros_field"
}

Jenis kompleks

Jenis data Avro	Jenis data BigQuery	Notes
record	RECORD	Alias diabaikan Dokumen dikonversi ke deskripsi kolom Nilai default ditetapkan pada waktu baca Urutan diabaikan Kolom rekursif dihapus — Hanya tingkat pertama penyusunan yang dipertahankan untuk kolom rekursif
enum	STRING	String adalah nilai simbolis enum Alias diabaikan Dokumen dikonversi ke deskripsi kolom
array	kolom berulang	Array array tidak didukung. Array yang hanya berisi jenis NULL akan diabaikan.
map<T>	RECORD	BigQuery mengonversi kolom map<T> Avro ke RECORD berulang yang berisi dua kolom: kunci dan nilai. BigQuery menyimpan kunci sebagai STRING, dan mengonversi nilai ke jenis data yang sesuai di BigQuery.
gabungan	Kolom nullable RECORD dengan daftar kolom nullable	Jika union hanya memiliki satu jenis non-null, union akan dikonversi menjadi kolom nullable. Jika tidak, jenis data ini akan dikonversi menjadi RECORD dengan daftar kolom nullable. Hanya salah satu dari kolom tersebut yang akan ditetapkan pada waktu baca.
tetap	BYTES	Alias diabaikan Ukuran diabaikan

Batasan

• Pemformatan array bertingkat tidak didukung di BigQuery. File Avro yang menggunakan format ini harus dikonversi sebelum diimpor.
• Di file Avro, nama dan namespace untuk nama lengkap hanya boleh berisi karakter alfanumerik dan karakter garis bawah _. Ekspresi reguler berikut menunjukkan karakter yang diizinkan: [A-Za-z_][A-Za-z0-9_]*

Untuk mengetahui informasi selengkapnya, lihat Batas tugas pemuatan BigQuery.