Memuat data JSON dari Cloud Storage
Anda dapat memuat data JSON yang dipisahkan newline dari Cloud Storage ke tabel atau partisi baru, atau menambahkan ke atau menimpa tabel atau partisi yang sudah ada. Ketika 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.
Format JSON yang dipisahkan newline memiliki format yang sama dengan format JSON Lines.
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.
Saat Anda memuat file JSON ke BigQuery, perhatikan hal berikut:
- Data JSON harus dipisahkan newline. Setiap objek JSON harus berada di baris terpisah dalam file.
- Jika Anda menggunakan kompresi gzip, BigQuery tidak dapat membaca data secara paralel. Memuat data JSON terkompresi ke BigQuery lebih lambat daripada pemuatan data yang tidak dikompresi.
- Anda tidak dapat menyertakan file yang dikompresi dan tidak dikompresi dalam tugas pemuatan yang sama.
- Ukuran maksimum file gzip adalah 4 GB.
BigQuery mendukung jenis
JSON
meskipun informasi skema tidak diketahui pada saat penyerapan. Kolom yang dideklarasikan sebagai jenisJSON
dimuat dengan nilai JSON mentah.Jika Anda menggunakan BigQuery API untuk memuat bilangan bulat di luar rentang [-253+1, 253-1] (biasanya ini berarti lebih besar dari 9.007.199.254.740.991), ke dalam kolom integer (INT64), teruskan sebagai string untuk menghindari kerusakan data. Masalah ini disebabkan oleh batasan ukuran bilangan bulat di JSON/ECMAScript. Untuk mengetahui informasi selengkapnya, lihat bagian Angka pada RFC 7159.
- Saat Anda memuat data CSV atau JSON, nilai dalam kolom
DATE
harus menggunakan pemisah tanda hubung (-
) dan tanggal harus dalam format berikut:YYYY-MM-DD
(tahun-bulan -hari). - Saat Anda memuat data JSON atau CSV, nilai dalam kolom
TIMESTAMP
harus menggunakan tanda hubung (-
) atau garis miring (/
) untuk bagian tanggal stempel waktu, dan tanggal harus dalam salah satu format berikut:YYYY-MM-DD
(tahun-bulan-hari) atauYYYY/MM/DD
(tahun/bulan/hari). Bagianhh:mm:ss
(jam-menit-detik) dari stempel waktu harus menggunakan pemisah titik dua (:
). File Anda harus memenuhi batas ukuran file JSON yang dijelaskan dalam batas tugas pemuatan.
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 izinbigquery.jobs.create
)bigquery.user
(termasuk izinbigquery.jobs.create
)bigquery.jobUser
(termasuk izinbigquery.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 lainnya yang telah ditetapkan sebelumnya.
Membuat set data
Buat set data BigQuery untuk menyimpan data Anda.
Kompresi JSON
Anda dapat menggunakan utilitas gzip
untuk mengompresi file JSON. Perhatikan bahwa gzip
melakukan kompresi file
lengkap, tidak seperti kompresi konten file yang dilakukan oleh
codec kompresi untuk format file lain, seperti Avro. Menggunakan gzip
untuk
mengompresi file JSON mungkin akan memengaruhi performa; untuk informasi selengkapnya
tentang kompromi, lihat
Memuat data yang dikompresi dan tidak dikompresi.
Memuat data JSON ke dalam tabel baru
Untuk memuat data JSON dari Cloud Storage ke tabel BigQuery baru:
Konsol
Di konsol Google Cloud, buka halaman BigQuery.
- Di panel Explorer, luaskan project Anda, lalu pilih set data.
- Di bagian Dataset info, klik Create table.
- Di panel Create table, tentukan detail berikut:
- Di bagian Source, pilih Google Cloud Storage dalam daftar Create table from.
Kemudian, lakukan hal berikut:
- 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.
- Untuk File format, pilih JSONL (Newline delimited JSON).
- Di bagian Destination, tentukan detail berikut:
- Untuk Dataset, pilih set data tempat Anda ingin membuat tabel.
- Di kolom Table, masukkan nama tabel yang ingin Anda buat.
- Pastikan kolom Table type disetel ke Native table.
- Di bagian Schema, masukkan definisi
schema.
Untuk mengaktifkan deteksi otomatis dari suatu skema,
pilih Auto detect.
Anda dapat memasukkan informasi skema secara manual menggunakan salah satu
metode berikut:
- Opsi 1: Klik Edit as text dan tempelkan skema dalam bentuk array JSON. Saat menggunakan array JSON, Anda menghasilkan skema menggunakan proses yang sama seperti membuat file skema JSON.
Anda dapat melihat skema tabel yang ada dalam format JSON dengan memasukkan perintah berikut:
bq show --format=prettyjson dataset.table
- Opsi 2: Klik Type, dan Mode untuk setiap kolom. Add field, lalu masukkan skema tabel. Tentukan Name,
- Opsi 1: Klik Edit as text dan tempelkan skema dalam bentuk array JSON. Saat menggunakan array JSON, Anda menghasilkan skema menggunakan proses yang sama seperti membuat file skema JSON.
Anda dapat melihat skema tabel yang ada dalam format JSON dengan memasukkan perintah berikut:
- Opsional: Tentukan Partition and cluster settings. Untuk mengetahui informasi selengkapnya, lihat Membuat tabel berpartisi serta Membuat dan menggunakan tabel yang dikelompokkan.
- 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.
- Untuk Number of errors allowed, terima nilai default
0
atau masukkan jumlah maksimum baris berisi error yang dapat diabaikan. Jika jumlah baris yang berisi error melebihi nilai ini, tugas akan menghasilkan pesaninvalid
dan gagal. Opsi ini hanya berlaku untuk file CSV dan JSON. - 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.
- Klik Buat tabel.
SQL
Gunakan
pernyataan DDL LOAD DATA
.
Contoh berikut memuat file JSON ke tabel baru mytable
:
Di konsol Google Cloud, buka halaman BigQuery.
Di editor kueri, masukkan pernyataan berikut:
LOAD DATA OVERWRITE mydataset.mytable (x INT64,y STRING) FROM FILES ( format = 'JSON', uris = ['gs://bucket/path/file.json']);
Klik
Run.
Untuk informasi selengkapnya tentang cara menjalankan kueri, lihat Menjalankan kueri interaktif.
bq
Gunakan perintah bq load
, tentukan NEWLINE_DELIMITED_JSON
menggunakan flag
--source_format
, dan sertakan Cloud Storage URI.
Anda dapat menyertakan URI tunggal, daftar URI yang dipisahkan koma, atau URI
yang berisi karakter pengganti.
Berikan skema secara inline, dalam file definisi skema, atau gunakan
deteksi otomatis skema.
(Opsional) Berikan flag --location
dan tetapkan nilainya ke lokasi Anda.
Flag opsional lainnya meliputi:
--max_bad_records
: Bilangan bulat yang menentukan jumlah maksimum kumpulan data buruk yang diizinkan sebelum seluruh tugas gagal. Nilai defaultnya adalah0
. Maksimal lima error dari jenis apa pun akan ditampilkan, terlepas dari nilai--max_bad_records
.--ignore_unknown_values
: Jika ditentukan, mengizinkan dan mengabaikan nilai tambahan yang tidak dikenali dalam data CSV atau JSON.--autodetect
: Jika ditentukan, mengaktifkan deteksi otomatis skema untuk data CSV dan JSON.--time_partitioning_type
: Mengaktifkan partisi berbasis waktu pada tabel dan menetapkan jenis partisi. Nilai yang mungkin adalahHOUR
,DAY
,MONTH
, danYEAR
. Flag ini bersifat opsional saat Anda membuat tabel yang dipartisi pada kolomDATE
,DATETIME
, atauTIMESTAMP
. Jenis partisi default untuk partisi berbasis waktu adalahDAY
. 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
: KolomDATE
atauTIMESTAMP
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 klausaWHERE
yang menentukan partisi yang akan dikueri. Mewajibkan filter partisi dapat mengurangi biaya dan meningkatkan performa. Untuk mengetahui informasi selengkapnya, lihat Membuat kueri tabel berpartisi.--clustering_fields
: Daftar yang dipisahkan koma yang berisi maksimum empat nama kolom yang digunakan untuk membuat tabel yang dikelompokkan.--destination_kms_key
: Kunci Cloud KMS untuk enkripsi data tabel.Untuk mengetahui informasi selengkapnya tentang tabel berpartisi, lihat:
Untuk mengetahui informasi selengkapnya tentang tabel yang dikelompokkan, lihat:
Untuk mengetahui informasi selengkapnya tentang enkripsi tabel, lihat:
Untuk memuat data JSON ke BigQuery, masukkan perintah berikut:
bq --location=LOCATION load \ --source_format=FORMAT \ DATASET.TABLE \ PATH_TO_SOURCE \ SCHEMA
Ganti kode berikut:
LOCATION
: lokasi Anda. Flag--location
bersifat opsional. Misalnya, jika menggunakan BigQuery di region Tokyo, Anda dapat menetapkan nilai flag keasia-northeast1
. Anda dapat menetapkan nilai default untuk lokasi menggunakan file .bigqueryrc.FORMAT
:NEWLINE_DELIMITED_JSON
.DATASET
: set data yang sudah ada.TABLE
: nama tabel tempat Anda memuat data.PATH_TO_SOURCE
: Cloud Storage URI yang sepenuhnya memenuhi syarat atau daftar URI yang dipisahkan koma. Karakter pengganti juga didukung.SCHEMA
: skema yang valid. Skema dapat berupa file JSON lokal, atau dapat diketik secara inline sebagai bagian dari perintah. Jika Anda menggunakan file skema, jangan berikan ekstensi. Anda juga dapat menggunakan flag--autodetect
alih-alih memberikan definisi skema.
Contoh:
Perintah berikut memuat data dari gs://mybucket/mydata.json
ke
tabel bernama mytable
di mydataset
. Skema ditentukan dalam file skema
lokal bernama myschema
.
bq load \
--source_format=NEWLINE_DELIMITED_JSON \
mydataset.mytable \
gs://mybucket/mydata.json \
./myschema
Perintah berikut memuat data dari gs://mybucket/mydata.json
ke tabel
yang dipartisi untuk waktu penyerapan baru bernama mytable
di mydataset
. Skema
ditentukan dalam file skema lokal bernama myschema
.
bq load \
--source_format=NEWLINE_DELIMITED_JSON \
--time_partitioning_type=DAY \
mydataset.mytable \
gs://mybucket/mydata.json \
./myschema
Perintah berikut memuat data dari gs://mybucket/mydata.json
ke
tabel yang dipartisi dengan nama mytable
di mydataset
. Tabel dipartisi
pada kolom mytimestamp
. Skema ditetapkan dalam file skema lokal bernama myschema
.
bq load \
--source_format=NEWLINE_DELIMITED_JSON \
--time_partitioning_field mytimestamp \
mydataset.mytable \
gs://mybucket/mydata.json \
./myschema
Perintah berikut memuat data dari gs://mybucket/mydata.json
ke
tabel bernama mytable
di mydataset
. Skema terdeteksi secara otomatis.
bq load \
--autodetect \
--source_format=NEWLINE_DELIMITED_JSON \
mydataset.mytable \
gs://mybucket/mydata.json
Perintah berikut memuat data dari gs://mybucket/mydata.json
ke
tabel bernama mytable
di mydataset
. Skema ditentukan secara inline dalam
format FIELD:DATA_TYPE, FIELD:DATA_TYPE
.
bq load \
--source_format=NEWLINE_DELIMITED_JSON \
mydataset.mytable \
gs://mybucket/mydata.json \
qtr:STRING,sales:FLOAT,year:STRING
Perintah berikut memuat data dari beberapa file di gs://mybucket/
ke dalam tabel bernama mytable
di mydataset
. URI Cloud Storage menggunakan karakter pengganti. Skema terdeteksi secara otomatis.
bq load \
--autodetect \
--source_format=NEWLINE_DELIMITED_JSON \
mydataset.mytable \
gs://mybucket/mydata*.json
Perintah berikut memuat data dari beberapa file di gs://mybucket/
ke dalam tabel bernama mytable
di mydataset
. Perintah ini menyertakan daftar URI Cloud Storage yang dipisahkan koma dengan karakter pengganti. Skema
ditentukan dalam file skema lokal bernama myschema
.
bq load \
--source_format=NEWLINE_DELIMITED_JSON \
mydataset.mytable \
"gs://mybucket/00/*.json","gs://mybucket/01/*.json" \
./myschema
API
Buat tugas
load
yang mengarah ke data sumber di Cloud Storage.(Opsional) Tentukan lokasi Anda di properti
location
di bagianjobReference
pada resource tugas.Properti
source URIs
harus sepenuhnya memenuhi syarat, dalam formatgs://BUCKET/OBJECT
. Setiap URI dapat berisi satu karakter pengganti '*'.Tentukan format data
JSON
dengan menetapkan propertisourceFormat
keNEWLINE_DELIMITED_JSON
.Untuk memeriksa status tugas, panggil
jobs.get(JOB_ID*)
, dengan menggantiJOB_ID
dengan ID tugas yang ditampilkan oleh permintaan awal.- Jika
status.state = DONE
, tugas berhasil diselesaikan. - Jika properti
status.errorResult
ada, permintaan gagal, dan objek tersebut menyertakan informasi yang menjelaskan apa yang salah. Jika permintaan gagal, tidak ada tabel yang dibuat dan tidak ada data yang dimuat. - Jika
status.errorResult
tidak ada, tugas berhasil diselesaikan; meskipun mungkin ada beberapa error tidak fatal, seperti masalah mengimpor beberapa baris. Error tidak fatal tercantum dalam propertistatus.errors
objek tugas yang ditampilkan.
- Jika
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 memanggiljobs.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 lagi sebanyak yang Anda inginkan pada ID pekerjaan yang sama, dan maksimal salah satu 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 mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.
Gunakan metodeBigQueryClient.CreateLoadJob()
untuk memulai tugas pemuatan dari Cloud Storage. Untuk menggunakan JSON yang dibatasi baris baru, buat
objek CreateLoadJobOptions
dan tetapkan
properti
SourceFormat
ke
FileFormat.NewlineDelimitedJson
.
Go
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Go di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Go API.
Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.
Java
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Java di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Java API.
Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.
Gunakan metode LoadJobConfiguration.builder(tableId, sourceUri) untuk memulai tugas pemuatan dari Cloud Storage. Untuk menggunakan JSON yang dibatasi baris baru, gunakan LoadJobConfiguration.setFormatOptions(FormatOptions.json()).
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.
PHP
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan PHP di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery PHP API.
Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.
Python
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Python API.
Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.
Gunakan metode Client.load_table_from_uri() untuk memulai tugas pemuatan dari Cloud Storage. Untuk menggunakan JSON yang dibatasi baris baru, tetapkan properti LoadJobConfig.source_format ke stringNEWLINE_DELIMITED_JSON
dan teruskan konfigurasi tugas sebagai
argumen job_config
ke metode load_table_from_uri()
.
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 mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.
Gunakan metode Dataset.load_job() untuk memulai tugas pemuatan dari Cloud Storage. Untuk menggunakan JSON yang dibatasi baris baru, tetapkan parameterformat
ke "json"
.
Memuat data JSON bertingkat dan berulang
BigQuery mendukung pemuatan data bertingkat dan berulang dari format sumber yang mendukung skema berbasis objek, seperti JSON, Avro, ORC, Parquet, Firestore, dan Datastore.
Satu objek JSON, termasuk kolom bertingkat/berulang, harus muncul di setiap baris.
Contoh berikut menunjukkan contoh data bertingkat/berulang. Tabel ini berisi informasi tentang orang-orang. Terdiri dari kolom berikut:
id
first_name
last_name
dob
(Tanggal lahir)addresses
(kolom bertingkat dan berulang)addresses.status
(saat ini atau sebelumnya)addresses.address
addresses.city
addresses.state
addresses.zip
addresses.numberOfYears
(tahun di alamat)
File data JSON akan terlihat seperti berikut. Perhatikan bahwa kolom alamat
berisi array nilai (ditunjukkan dengan [ ]
).
{"id":"1","first_name":"John","last_name":"Doe","dob":"1968-01-22","addresses":[{"status":"current","address":"123 First Avenue","city":"Seattle","state":"WA","zip":"11111","numberOfYears":"1"},{"status":"previous","address":"456 Main Street","city":"Portland","state":"OR","zip":"22222","numberOfYears":"5"}]} {"id":"2","first_name":"Jane","last_name":"Doe","dob":"1980-10-16","addresses":[{"status":"current","address":"789 Any Avenue","city":"New York","state":"NY","zip":"33333","numberOfYears":"2"},{"status":"previous","address":"321 Main Street","city":"Hoboken","state":"NJ","zip":"44444","numberOfYears":"3"}]}
Skema untuk tabel ini akan terlihat seperti berikut:
[ { "name": "id", "type": "STRING", "mode": "NULLABLE" }, { "name": "first_name", "type": "STRING", "mode": "NULLABLE" }, { "name": "last_name", "type": "STRING", "mode": "NULLABLE" }, { "name": "dob", "type": "DATE", "mode": "NULLABLE" }, { "name": "addresses", "type": "RECORD", "mode": "REPEATED", "fields": [ { "name": "status", "type": "STRING", "mode": "NULLABLE" }, { "name": "address", "type": "STRING", "mode": "NULLABLE" }, { "name": "city", "type": "STRING", "mode": "NULLABLE" }, { "name": "state", "type": "STRING", "mode": "NULLABLE" }, { "name": "zip", "type": "STRING", "mode": "NULLABLE" }, { "name": "numberOfYears", "type": "STRING", "mode": "NULLABLE" } ] } ]
Untuk informasi tentang cara menentukan skema bertingkat dan berulang, lihat Menentukan kolom bertingkat dan berulang.
Memuat data JSON semi-terstruktur
BigQuery mendukung pemuatan data semi-terstruktur, dengan kolom yang dapat mengambil nilai dari berbagai jenis. Contoh berikut menunjukkan data yang mirip dengan contoh data JSON bertingkat dan berulang sebelumnya, kecuali kolom address
bisa berupa STRING
, kolom STRUCT
, atau
ARRAY
:
{"id":"1","first_name":"John","last_name":"Doe","dob":"1968-01-22","address":"123 First Avenue, Seattle WA 11111"} {"id":"2","first_name":"Jane","last_name":"Doe","dob":"1980-10-16","address":{"status":"current","address":"789 Any Avenue","city":"New York","state":"NY","zip":"33333","numberOfYears":"2"}} {"id":"3","first_name":"Bob","last_name":"Doe","dob":"1982-01-10","address":[{"status":"current","address":"789 Any Avenue","city":"New York","state":"NY","zip":"33333","numberOfYears":"2"}, "321 Main Street Hoboken NJ 44444"]}
Anda dapat memuat data ini ke BigQuery menggunakan skema berikut:
[ { "name": "id", "type": "STRING", "mode": "NULLABLE" }, { "name": "first_name", "type": "STRING", "mode": "NULLABLE" }, { "name": "last_name", "type": "STRING", "mode": "NULLABLE" }, { "name": "dob", "type": "DATE", "mode": "NULLABLE" }, { "name": "address", "type": "JSON", "mode": "NULLABLE" } ]
Kolom address
dimuat ke dalam kolom dengan jenis
JSON
yang memungkinkan
untuk menyimpan
jenis campuran dalam contoh. Anda dapat menyerap data sebagai JSON
, baik data tersebut berisi jenis campuran maupun tidak. Misalnya, Anda dapat menentukan JSON
, bukan
STRING
sebagai jenis untuk kolom first_name
. Untuk mengetahui informasi selengkapnya, baca bagian Bekerja dengan data JSON di GoogleSQL.
Menambahkan atau menimpa tabel dengan data JSON
Anda dapat memuat data tambahan ke dalam tabel dari file sumber atau dengan menambahkan hasil kueri.
Di Konsol Google Cloud, gunakan opsi Write preference untuk menentukan tindakan yang harus diambil ketika Anda memuat data dari file sumber atau dari hasil kueri.
Anda memiliki opsi berikut saat memuat data tambahan ke dalam tabel:
Opsi konsol | flag alat bq | Properti BigQuery API | Deskripsi |
---|---|---|---|
Tulis jika kosong | Tidak didukung | WRITE_EMPTY |
Menulis data hanya jika tabel kosong. |
Tambahkan ke tabel | --noreplace atau --replace=false ; jika
--[no]replace tidak ditentukan, defaultnya adalah menambahkan |
WRITE_APPEND |
(Default) Menambahkan data ke akhir tabel. |
Timpa tabel | --replace atau --replace=true |
WRITE_TRUNCATE |
Menghapus semua data yang ada di tabel sebelum menulis data baru. Tindakan ini juga akan menghapus skema tabel dan keamanan tingkat baris, serta menghapus kunci Cloud KMS apa pun. |
Jika Anda memuat data ke dalam tabel yang sudah ada, tugas pemuatan dapat menambahkan data atau menimpa tabel.
Anda dapat menambahkan atau menimpa tabel menggunakan salah satu cara berikut:
- Konsol Google Cloud
- Perintah
bq load
alat command line bq - Metode API
jobs.insert
dan mengonfigurasi tugasload
- Library klien
Konsol
Di konsol Google Cloud, buka halaman BigQuery.
- Di panel Explorer, luaskan project Anda, lalu pilih set data.
- Di bagian Dataset info, klik Create table.
- Di panel Create table, tentukan detail berikut:
- Di bagian Source, pilih Google Cloud Storage dalam daftar Create table from.
Kemudian, lakukan hal berikut:
- 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.
- Untuk File format, pilih JSONL (Newline delimited JSON).
- Di bagian Destination, tentukan detail berikut:
- Untuk Dataset, pilih set data tempat Anda ingin membuat tabel.
- Di kolom Table, masukkan nama tabel yang ingin Anda buat.
- Pastikan kolom Table type disetel ke Native table.
- Di bagian Schema, masukkan definisi
schema.
Untuk mengaktifkan deteksi otomatis dari suatu skema,
pilih Auto detect.
Anda dapat memasukkan informasi skema secara manual menggunakan salah satu
metode berikut:
- Opsi 1: Klik Edit as text dan tempelkan skema dalam bentuk array JSON. Saat menggunakan array JSON, Anda menghasilkan skema menggunakan proses yang sama seperti membuat file skema JSON.
Anda dapat melihat skema tabel yang ada dalam format JSON dengan memasukkan perintah berikut:
bq show --format=prettyjson dataset.table
- Opsi 2: Klik Type, dan Mode untuk setiap kolom. Add field, lalu masukkan skema tabel. Tentukan Name,
- Opsi 1: Klik Edit as text dan tempelkan skema dalam bentuk array JSON. Saat menggunakan array JSON, Anda menghasilkan skema menggunakan proses yang sama seperti membuat file skema JSON.
Anda dapat melihat skema tabel yang ada dalam format JSON dengan memasukkan perintah berikut:
- 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.
- Klik Advanced options, lalu lakukan tindakan berikut:
- Untuk Write preference, pilih Append to table atau Overwrite table.
- Untuk Number of errors allowed, terima nilai default
0
atau masukkan jumlah maksimum baris berisi error yang dapat diabaikan. Jika jumlah baris yang berisi error melebihi nilai ini, tugas akan menghasilkan pesaninvalid
dan gagal. Opsi ini hanya berlaku untuk file CSV dan JSON. - 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.
- Klik Buat tabel.
SQL
Gunakan pernyataan DDL LOAD DATA
.
Contoh berikut menambahkan file JSON ke tabel mytable
:
Di Konsol Google Cloud, buka halaman BigQuery.
Di editor kueri, masukkan pernyataan berikut:
LOAD DATA INTO mydataset.mytable FROM FILES ( format = 'JSON', uris = ['gs://bucket/path/file.json']);
Klik
Run.
Untuk informasi selengkapnya tentang cara menjalankan kueri, lihat Menjalankan kueri interaktif.
bq
Gunakan perintah bq load
, tentukan NEWLINE_DELIMITED_JSON
menggunakan flag
--source_format
, dan sertakan Cloud Storage URI.
Anda dapat menyertakan URI tunggal, daftar URI yang dipisahkan koma, atau URI
yang berisi karakter pengganti.
Berikan skema secara inline, dalam file definisi skema, atau gunakan deteksi otomatis skema.
Tentukan flag --replace
untuk menimpa tabel. Gunakan flag --noreplace
untuk menambahkan data ke tabel. Jika tidak ada flag yang ditentukan, defaultnya adalah menambahkan data.
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:
--max_bad_records
: Bilangan bulat yang menentukan jumlah maksimum kumpulan data buruk yang diizinkan sebelum seluruh tugas gagal. Nilai defaultnya adalah0
. Maksimal lima error dari jenis apa pun akan ditampilkan, terlepas dari nilai--max_bad_records
.--ignore_unknown_values
: Jika ditentukan, mengizinkan dan mengabaikan nilai tambahan yang tidak dikenali dalam data CSV atau JSON.--autodetect
: Jika ditentukan, mengaktifkan deteksi otomatis skema untuk data CSV dan JSON.--destination_kms_key
: Kunci Cloud KMS untuk enkripsi data tabel.
bq --location=LOCATION load \ --[no]replace \ --source_format=FORMAT \ DATASET.TABLE \ PATH_TO_SOURCE \ SCHEMA
Ganti kode berikut:
LOCATION
: lokasi Anda. Flag--location
bersifat opsional. Anda dapat menetapkan nilai default untuk lokasi menggunakan file.bigqueryrc.FORMAT
:NEWLINE_DELIMITED_JSON
.DATASET
: set data yang sudah ada.TABLE
: nama tabel tempat Anda memuat data.PATH_TO_SOURCE
: Cloud Storage URI yang sepenuhnya memenuhi syarat atau daftar URI yang dipisahkan koma. Karakter pengganti juga didukung.SCHEMA
: skema yang valid. Skema dapat berupa file JSON lokal, atau dapat diketik secara inline sebagai bagian dari perintah. Anda juga dapat menggunakan flag--autodetect
alih-alih memberikan definisi skema.
Contoh:
Perintah berikut memuat data dari gs://mybucket/mydata.json
dan menimpa tabel bernama mytable
di mydataset
. Skema ditentukan menggunakan deteksi otomatis skema.
bq load \
--autodetect \
--replace \
--source_format=NEWLINE_DELIMITED_JSON \
mydataset.mytable \
gs://mybucket/mydata.json
Perintah berikut memuat data dari gs://mybucket/mydata.json
dan menambahkan data ke tabel bernama mytable
di mydataset
. Skema
ditentukan menggunakan file skema JSON — myschema
.
bq load \
--noreplace \
--source_format=NEWLINE_DELIMITED_JSON \
mydataset.mytable \
gs://mybucket/mydata.json \
./myschema
API
Buat tugas
load
yang mengarah ke data sumber di Cloud Storage.(Opsional) Tentukan lokasi Anda di properti
location
di bagianjobReference
pada resource tugas.Properti
source URIs
harus sepenuhnya memenuhi syarat, dalam formatgs://BUCKET/OBJECT
. Anda dapat menyertakan beberapa URI sebagai daftar yang dipisahkan koma. Karakter pengganti juga didukung.Tentukan format data dengan menetapkan properti
configuration.load.sourceFormat
keNEWLINE_DELIMITED_JSON
.Tentukan preferensi tulis dengan menetapkan properti
configuration.load.writeDisposition
keWRITE_TRUNCATE
atauWRITE_APPEND
.
Go
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Go di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Go API.
Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.
Java
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.
PHP
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan PHP di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery PHP API.
Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.
Python
Untuk mengganti baris dalam tabel yang ada, tetapkan
properti LoadJobConfig.write_disposition
ke string WRITE_TRUNCATE
.
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.
Ruby
Untuk mengganti baris dalam tabel yang ada, tetapkan parameter write
dari
Table.load_job()
ke "WRITE_TRUNCATE"
.
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 mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.
Memuat data JSON yang dipartisi hive
BigQuery mendukung pemuatan data JSON yang dipartisi hive yang disimpan di Cloud Storage dan mengisi kolom partisi hive sebagai kolom di tabel terkelola BigQuery tujuan. Untuk informasi selengkapnya, lihat Memuat data yang dipartisi secara eksternal.
Detail pemuatan data JSON
Bagian ini menjelaskan cara BigQuery mengurai berbagai jenis data saat memuat data JSON.
Jenis data
Boolean. BigQuery dapat mengurai salah satu pasangan berikut untuk data Boolean: 1 atau 0, benar atau salah, t atau f, ya atau tidak, atau y atau n (semua tidak peka huruf besar/kecil). Skema deteksi otomatis otomatis mendeteksi salah satu dari tiga hal tersebut, kecuali 0 dan 1.Bytes. Kolom dengan jenis BYTES harus dienkode sebagai Base64.
Date. Kolom dengan jenis DATE harus dalam format YYYY-MM-DD
.
Datetime. Kolom dengan jenis DATETIME harus dalam format YYYY-MM-DD
HH:MM:SS[.SSSSSS]
.
Geography. Kolom dengan jenis GEOGRAPHY harus berisi string dalam salah satu format berikut:
- Well-known text (WKT)
- Well-known binary (WKB)
- GeoJSON
Jika Anda menggunakan WKB, nilainya harus berenkode hex.
Daftar berikut menunjukkan contoh data yang valid:
- WKT:
POINT(1 2)
- GeoJSON:
{ "type": "Point", "coordinates": [1, 2] }
- WKB dengan enkode heksadesimal:
0101000000feffffffffffef3f0000000000000040
Sebelum memuat data GEOGRAPHY, baca juga Memuat data geospasial.
Interval. Kolom dengan jenis INTERVAL harus dalam
format ISO 8601
PYMDTHMS
, dengan:
- P = Penanda yang menunjukkan bahwa nilai mewakili durasi. Anda harus selalu menyertakan ini.
- Y = Tahun
- M = Bulan
- D = Hari
- T = Penanda yang menunjukkan bagian waktu dari durasi. Anda harus selalu menyertakan ini.
- H = Jam
- M = Menit
- S = Detik. Detik dapat dilambangkan sebagai nilai keseluruhan atau sebagai nilai pecahan hingga enam digit, dengan presisi mikrodetik.
Anda dapat menunjukkan nilai negatif dengan menambahkan tanda hubung (-).
Daftar berikut menunjukkan contoh data yang valid:
P-10000Y0M-3660000DT-87840000H0M0S
P0Y0M0DT0H0M0.000001S
P10000Y0M3660000DT87840000H0M0S
Untuk memuat data INTERVAL, Anda harus menggunakan perintah bq load
dan menggunakan tanda --schema
untuk menentukan skema. Anda tidak dapat mengupload data INTERVAL dengan menggunakan konsol.
Time. Kolom dengan jenis TIME harus dalam format HH:MM:SS[.SSSSSS]
.
Timestamp. BigQuery menerima berbagai format stempel waktu. Stempel waktu harus menyertakan bagian tanggal dan bagian waktu.
Bagian tanggal dapat diformat sebagai
YYYY-MM-DD
atauYYYY/MM/DD
.Bagian stempel waktu harus diformat sebagai
HH:MM[:SS[.SSSSSS]]
(detik dan fraksi detik bersifat opsional).Tanggal dan waktu harus dipisahkan dengan spasi atau 'T'.
Secara opsional, tanggal dan waktu dapat diikuti dengan offset UTC atau penanda zona UTC (
Z
). Untuk mengetahui informasi selengkapnya, lihat Zona waktu.
Misalnya, salah satu dari berikut ini adalah nilai stempel waktu yang valid:
- 2018-08-19 12:11
- 2018-08-19 12:11:35
- 2018-08-19 12:11:35.22
- 2018/08/19 12:11
- 2018-07-05 12:54:00 UTC
- 2018-08-19 07:11:35.220 -05:00
- 2018-08-19T12:11:35.220Z
Jika Anda memberikan skema, BigQuery juga menerima waktu epoch Unix untuk nilai stempel waktu. Namun, deteksi otomatis skema tidak mendeteksi kasus ini, dan memperlakukan nilai sebagai jenis numerik atau string.
Contoh nilai stempel waktu Unix epoch:
- 1534680695
- 1.534680695e11
Array (kolom berulang). Nilai harus berupa array JSON atau null
. JSON
null
dikonversi ke SQL NULL
. Array itu sendiri tidak boleh berisi nilai
null
.
Deteksi otomatis skema
Bagian ini menjelaskan perilaku deteksi otomatis skema saat memuat file JSON.
Kolom bertingkat dan berulang JSON
BigQuery menyimpulkan kolom bertingkat dan berulang dalam file JSON. Jika nilai kolom adalah objek JSON, BigQuery akan memuat kolom sebagai jenis RECORD
. Jika nilai kolom adalah array, BigQuery akan memuat kolom tersebut sebagai kolom berulang. Untuk contoh data JSON dengan data bertingkat dan berulang, lihat Memuat data JSON bertingkat dan berulang.
Konversi string
Jika Anda mengaktifkan deteksi otomatis skema, BigQuery akan mengonversi string menjadi jenis Boolean, numerik, atau tanggal/waktu jika memungkinkan. Misalnya, dengan menggunakan data JSON berikut, deteksi otomatis skema akan mengonversi kolom id
menjadi kolom INTEGER
:
{ "name":"Alice","id":"12"}
{ "name":"Bob","id":"34"}
{ "name":"Charles","id":"45"}
Jenis encoding
BigQuery mengharapkan data JSON berenkode UTF-8. Jika memiliki file JSON dengan jenis encoding lain yang didukung, Anda harus secara eksplisit menentukan encoding menggunakan flag --encoding
agar BigQuery mengonversi data ke UTF- 8
BigQuery mendukung jenis encoding berikut untuk file JSON:
- UTF-8
- ISO-8859-1
- UTF-16BE (UTF-16 Big Endian)
- UTF-16LE (UTF-16 Little Endian)
- UTF-32BE (UTF-32 Big Endian)
- UTF-32LE (UTF-32 Little Endian)
Opsi JSON
Untuk mengubah cara BigQuery mengurai data JSON, tentukan opsi tambahan di konsol Google Cloud, alat command line bq, API, atau library klien.
Opsi JSON | Opsi konsol | flag alat bq | Properti BigQuery API | Deskripsi |
---|---|---|---|---|
Jumlah catatan buruk yang diizinkan | Jumlah error yang diizinkan: | --max_bad_records |
maxBadRecords
(Java,
Python)
|
(Opsional) Jumlah maksimum data buruk yang dapat diabaikan BigQuery saat menjalankan tugas. Jika jumlah catatan buruk melebihi nilai ini, error yang tidak valid akan ditampilkan di hasil tugas. Nilai defaultnya adalah `0`, yang mengharuskan semua data valid. |
Nilai tidak diketahui | Abaikan nilai yang tidak diketahui | --ignore_unknown_values |
ignoreUnknownValues
(Java,
Python)
|
(Opsional) Menunjukkan apakah BigQuery harus mengizinkan nilai tambahan yang tidak direpresentasikan dalam skema tabel. Jika true, nilai tambahan akan diabaikan. Jika false, kumpulan data dengan kolom tambahan akan dianggap sebagai kumpulan data buruk, dan jika ada terlalu banyak kumpulan data yang buruk, error yang tidak valid akan ditampilkan dalam hasil tugas. Nilai defaultnya adalah false. Properti `sourceFormat` menentukan apa yang diperlakukan BigQuery sebagai nilai tambahan: CSV: kolom akhir, JSON: nilai bernama yang tidak cocok dengan nama kolom mana pun. |
Encoding | Tidak ada | -E atau --encoding |
encoding
(Python) |
(Opsional) Encoding karakter data. Nilai yang didukung adalah UTF-8, ISO-8859-1, UTF-16BE, UTF-16LE, UTF-32BE, atau UTF-32LE. Nilai defaultnya adalah UTF-8. |
Langkah selanjutnya
- Untuk informasi tentang cara memuat data JSON dari file lokal, lihat Memuat data dari file lokal.
- Untuk mengetahui informasi selengkapnya tentang cara membuat, menyerap, dan membuat kueri data JSON, lihat Menangani data JSON di GoogleSQL.