Membuat file definisi tabel untuk sumber data eksternal
Halaman ini menjelaskan cara membuat file definisi tabel untuk sumber data eksternal. Sumber data eksternal adalah sumber data yang dapat langsung dibuat kuerinya meskipun data tersebut tidak disimpan di BigQuery.
File definisi tabel berisi definisi skema dan metadata tabel eksternal, seperti format data tabel dan properti terkait. Saat membuat file definisi tabel, Anda dapat menggunakan skema deteksi otomatis guna menentukan skema untuk sumber data eksternal. Anda dapat memberikan skema secara inline atau memberikan file JSON yang berisi definisi skema.
File definisi tabel digunakan dengan alat command line bq. Properti
dalam file definisi tabel juga berlaku untuk pembuatan
ExternalDataConfiguration
saat Anda menggunakan REST API. Anda tidak menggunakan file definisi tabel saat membuat
tabel eksternal menggunakan konsol Google Cloud.
Anda dapat membuat file definisi tabel untuk mendeskripsikan tabel eksternal permanen atau sementara untuk sumber data eksternal berikut:
Cloud Storage
- Nilai yang dipisahkan koma (CSV)
- JSON yang dibatasi baris baru
- File Avro
- File ekspor Datastore
- File ORC
- File Parquet
- File ekspor Firestore
Google Drive
- Nilai yang dipisahkan koma (CSV)
- JSON yang dibatasi baris baru
- File Avro
- Google Spreadsheet
Bigtable
Sebelum memulai
Untuk membuat file definisi tabel, Anda memerlukan URI untuk sumber data:
- Untuk sumber data Drive, Anda memerlukan URI Drive
- Untuk sumber data Cloud Storage, Anda memerlukan Cloud Storage URI
- Untuk sumber data Bigtable, Anda memerlukan URI Bigtable
Membuat file definisi untuk file CSV, JSON, atau Google Spreadsheet
Gunakan salah satu metode berikut untuk membuat file definisi tabel untuk file CSV, JSON, atau Google Spreadsheet di Cloud Storage atau Drive:
Menggunakan flag autodetect
Jika menentukan file CSV, JSON, atau Google Spreadsheet tanpa menyertakan deskripsi skema
inline atau file skema, Anda dapat menggunakan flag --autodetect
untuk mengatur opsi "autodetect"
untuk true
dalam file definisi tabel. Ketika
deteksi otomatis diaktifkan, BigQuery akan melakukan upaya terbaik untuk
menyimpulkan skema secara otomatis. Untuk mengetahui informasi selengkapnya, lihat
Deteksi otomatis skema untuk sumber data eksternal.
Menggunakan deteksi otomatis dengan sumber data Cloud Storage
Buat file definisi tabel untuk sumber data Cloud Storage:
Gunakan perintah
bq mkdef
dengan flag--autodetect
untuk membuat file definisi tabel. Perintahmkdef
akan menghasilkan file definisi tabel dalam format JSON. Contoh berikut akan membuat definisi tabel dan menulis output ke file:/tmp/file_name
.bq mkdef \ --autodetect \ --source_format=SOURCE_FORMAT \ "URI" > /tmp/FILE_NAME
Ganti kode berikut:
SOURCE_FORMAT
: format file AndaFILE_NAME
: nama file definisi tabelURI
: Cloud Storage URIMisalnya,
gs://mybucket/myfile
.
(Opsional) Buka file definisi tabel di editor teks. Misalnya, perintah
nano /tmp/file_name
akan membuka file di nano. File untuk sumber data eksternal CSV akan terlihat seperti berikut. Notifikasi"autodetect"
disetel ketrue
.{ "autodetect": true, "csvOptions": { "allowJaggedRows": false, "allowQuotedNewlines": false, "encoding": "UTF-8", "fieldDelimiter": ",", "quote": "\"", "skipLeadingRows": 0 }, "sourceFormat": "CSV", "sourceUris": [ "URI" ] }
(Opsional) Edit file definisi tabel secara manual untuk mengubah, menambahkan, atau menghapus setelan umum seperti
maxBadRecords
danignoreUnknownValues
. Tidak ada setelan konfigurasi yang khusus untuk file sumber JSON, tetapi ada setelan yang berlaku untuk CSV dan file Google Spreadsheet. Untuk informasi selengkapnya, lihatExternalDataConfiguration
dalam referensi API.
Menggunakan deteksi otomatis dengan sumber data Drive
Buat file definisi tabel untuk sumber data Drive:
Gunakan perintah
bq mkdef
dengan flag--autodetect
untuk membuat definisi tabel. Perintahmkdef
akan menghasilkan file definisi tabel dalam format JSON. Contoh berikut akan membuat definisi tabel dan menulis output ke file:/tmp/file_name
.bq mkdef \ --autodetect \ --source_format=SOURCE_FORMAT \ "URI" > /tmp/FILE_NAME
Ganti kode berikut:
SOURCE_FORMAT
: format file AndaFILE_NAME
: nama file definisi tabelURI
: URI DriveMisalnya,
https://drive.google.com/open?id=123ABCD123AbcD123Abcd
.
Buka file definisi tabel di editor teks. Misalnya, perintah
nano /tmp/file_name
akan membuka file tersebut di nano. File untuk sumber data eksternal Google Spreadsheet akan terlihat seperti berikut. Notifikasi"autodetect"
disetel ketrue
.{ "autodetect": true, "sourceFormat": "GOOGLE_SHEETS", "sourceUris": [ "URI" ] }
(Opsional) Edit file definisi tabel secara manual untuk mengubah, menambahkan, atau menghapus setelan umum seperti
maxBadRecords
danignoreUnknownValues
. Tidak ada setelan konfigurasi yang khusus untuk file sumber JSON, tetapi ada setelan yang berlaku untuk CSV dan file Google Spreadsheet. Untuk informasi selengkapnya, lihatExternalDataConfiguration
dalam referensi API.Untuk menentukan sheet atau rentang sel tertentu dalam file Google Spreadsheet, tambahkan properti
range
ke file definisi tabel. Untuk membuat kueri sheet tertentu, tentukan nama sheet. Untuk membuat kueri rentang sel, tentukan rentang dalam bentuk:sheet_name!top_left_cell_id:bottom_right_cell_id
, misalnya,"Sheet1!A1:B20"
. Jika parameterrange
tidak ditentukan, sheet pertama dalam file akan digunakan.
Menggunakan skema inline
Jika tidak ingin menggunakan deteksi otomatis skema, Anda dapat membuat file definisi tabel
dengan memberikan definisi skema inline. Untuk memberikan definisi skema
inline, cantumkan jenis data dan kolom pada command line dalam format
berikut: FIELD:DATA_TYPE,FIELD:DATA_TYPE
.
Menggunakan skema inline dengan sumber data Drive atau Cloud Storage
Buat definisi tabel untuk sumber data Cloud Storage atau Drive dengan menggunakan definisi skema inline:
Gunakan perintah
bq mkdef
dengan flag--noautodetect
untuk membuat definisi tabel. Perintahmkdef
akan menghasilkan file definisi tabel dalam format JSON. Contoh berikut akan membuat definisi tabel dan menulis output ke file:/tmp/file_name
.bq mkdef \ --noautodetect \ --source_format=SOURCE_FORMAT \ "URI" \ FIELD:DATA_TYPE,FIELD:DATA_TYPE > /tmp/FILE_NAME
Ganti kode berikut:
SOURCE_FORMAT
: format file sumberURI
: Cloud Storage URI atau URI DriveMisalnya,
gs://mybucket/myfile
untuk Cloud Storage atauhttps://drive.google.com/open?id=123ABCD123AbcD123Abcd
untuk Drive.FIELD:DATA_TYPE,FIELD:DATA_TYPE
: definisi skemaMisalnya,
Name:STRING,Address:STRING, ...
.FILE_NAME
: nama file definisi tabel
(Opsional) Buka file definisi tabel di editor teks. Misalnya, perintah
nano /tmp/file_name
akan membuka file di nano. Filenya akan terlihat seperti berikut. Notifikasi"autodetect"
tidak diaktifkan, dan informasi skema ditulis pada file definisi tabel.{ "schema": { "fields": [ { "name": "FIELD", "type": "DATA_TYPE" }, { "name": "FIELD", "type": "DATA_TYPE" } ... ] }, "sourceFormat": "NEWLINE_DELIMITED_JSON", "sourceUris": [ "URI" ] }
(Opsional) Edit file definisi tabel secara manual untuk mengubah, menambahkan, atau menghapus setelan umum seperti
maxBadRecords
danignoreUnknownValues
. Tidak ada setelan konfigurasi yang khusus untuk file sumber JSON, tetapi ada setelan yang berlaku untuk CSV dan file Google Spreadsheet. Untuk informasi selengkapnya, lihatExternalDataConfiguration
dalam referensi API.
Menggunakan file skema JSON
Jika tidak ingin menggunakan deteksi otomatis atau memberikan definisi skema inline, Anda dapat membuat file skema JSON dan mereferensikannya saat membuat file definisi tabel. Buat file skema JSON secara manual di komputer lokal Anda. Mereferensikan file skema JSON yang disimpan di Cloud Storage atau di Drive tidak didukung.
Menggunakan file skema dengan sumber data Cloud Storage
Buat definisi tabel untuk sumber data Cloud Storage menggunakan file skema JSON:
Gunakan perintah
bq mkdef
dengan flag--noautodetect
untuk membuat definisi tabel. Perintahmkdef
akan menghasilkan file definisi tabel dalam format JSON. Contoh berikut akan membuat definisi tabel dan menulis output ke file:/tmp/file_name
.bq mkdef \ --noautodetect \ --source_format=SOURCE_FORMAT \ "URI" \ PATH_TO_SCHEMA_FILE > /tmp/FILE_NAME
Ganti kode berikut:
SOURCE_FORMAT
: format file AndaFILE_NAME
: nama file definisi tabelURI
: Cloud Storage URIMisalnya,
gs://mybucket/myfile
.PATH_TO_SCHEMA_FILE
: lokasi file skema JSON di komputer lokal Anda
(Opsional) Buka file definisi tabel di editor teks. Misalnya, perintah
nano /tmp/file_name
akan membuka file dalam nano
. Filenya akan terlihat seperti berikut. Notifikasi"autodetect"
tidak diaktifkan, dan informasi skema ditulis pada file definisi tabel.{ "schema": { "fields": [ { "name": "FIELD", "type": "DATA_TYPE" }, { "name": "FIELD", "type": "DATA_TYPE" } ... ] }, "sourceFormat": "NEWLINE_DELIMITED_JSON", "sourceUris": [ "URI" ] }
(Opsional) Edit file definisi tabel secara manual untuk mengubah, menambahkan, atau menghapus setelan umum seperti
maxBadRecords
danignoreUnknownValues
. Tidak ada setelan konfigurasi yang khusus untuk file sumber JSON, tetapi ada setelan yang berlaku untuk CSV dan file Google Spreadsheet. Untuk informasi selengkapnya, lihatExternalDataConfiguration
dalam referensi API.
Menggunakan file skema dengan sumber data Drive
Buat definisi tabel untuk sumber data Drive menggunakan file skema JSON:
Gunakan perintah
bq mkdef
dengan flag--noautodetect
untuk membuat definisi tabel. Perintahmkdef
akan menghasilkan file definisi tabel dalam format JSON. Contoh berikut akan membuat definisi tabel dan menulis output ke file:/tmp/file_name
.bq mkdef \ --noautodetect \ --source_format=source_format \ "URI" \ PATH_TO_SCHEMA_FILE > /tmp/FILE_NAME
Ganti kode berikut:
SOURCE_FORMAT
: format file sumberURI
: URI DriveMisalnya,
https://drive.google.com/open?id=123ABCD123AbcD123Abcd
.PATH_TO_SCHEMA_FILE
: lokasi file skema JSON di komputer lokal AndaFILE_NAME
: nama file definisi tabel
Buka file definisi tabel di editor teks. Misalnya, perintah
nano /tmp/file_name
akan membuka file tersebut di nano. Filenya akan terlihat seperti berikut. Notifikasi"autodetect"
tidak diaktifkan, dan informasi skema ditulis pada file definisi tabel.{ "schema": { "fields": [ { "name": "FIELD", "type": "DATA_TYPE" }, { "name": "FIELD", "type": "DATA_TYPE" } ... ] }, "sourceFormat": "GOOGLE_SHEETS", "sourceUris": [ "URI" ] }
(Opsional) Edit file definisi tabel secara manual untuk mengubah, menambahkan, atau menghapus setelan umum seperti
maxBadRecords
danignoreUnknownValues
. Tidak ada setelan konfigurasi yang khusus untuk file sumber JSON, tetapi ada setelan yang berlaku untuk CSV dan file Google Spreadsheet. Untuk informasi selengkapnya, lihatExternalDataConfiguration
dalam referensi API.Untuk menentukan sheet atau rentang sel tertentu dalam file Google Spreadsheet, tambahkan properti
range
ke file definisi tabel. Untuk membuat kueri sheet tertentu, tentukan nama sheet. Untuk membuat kueri rentang sel, tentukan rentang dalam bentuk:sheet_name!top_left_cell_id:bottom_right_cell_id
, misalnya,"Sheet1!A1:B20"
. Jika parameterrange
tidak ditentukan, sheet pertama dalam file akan digunakan.
Membuat file definisi untuk format pendeskripsian mandiri
Avro, Parquet, dan ORC adalah format pendeskripsian mandiri. File data dalam format ini berisi informasi skemanya sendiri. Jika Anda menggunakan salah satu format ini sebagai sumber data eksternal, maka BigQuery akan otomatis mengambil skema menggunakan data sumber. Saat membuat definisi tabel, Anda tidak perlu menggunakan deteksi otomatis skema, dan tidak perlu memberikan definisi skema inline atau file skema.
Anda dapat membuat file definisi tabel untuk data Avro, Parquet, atau ORC yang disimpan di Cloud Storage atau Drive:
Gunakan perintah
bq mkdef
untuk membuat definisi tabel.bq mkdef \ --source_format=FORMAT \ "URI" > FILE_NAME
Ganti kode berikut:
FORMAT
: format sumberURI
: Cloud Storage URI atau URI DriveMisalnya,
gs://mybucket/myfile
untuk Cloud Storage atauhttps://drive.google.com/open?id=123ABCD123AbcD123Abcd
untuk Drive.FILE_NAME
: nama file definisi tabel
Opsional: Buka file definisi tabel di editor teks. Filenya akan terlihat mirip dengan yang berikut:
{ "sourceFormat": "AVRO", "sourceUris": [ "URI" ] }
Opsional: Edit file definisi tabel secara manual untuk mengubah, menambahkan, atau menghapus setelan umum seperti
maxBadRecords
danignoreUnknownValues
. Untuk informasi selengkapnya, lihatExternalDataConfiguration
dalam referensi API.
Membuat file definisi untuk data yang dipartisi hive
Gunakan perintah bq mkdef
dengan hive_partitioning_mode
dan flag
hive_partitioning_source_uri_prefix
guna
membuat file definisi untuk data yang dipartisi hive yang tersimpan di
Cloud Storage, Amazon Simple Storage Service (Amazon S3), atau Azure Blob Storage.
Membuat file definisi untuk Datastore dan Firestore
Jika Anda menggunakan ekspor Datastore atau Firestore sebagai sumber data eksternal, BigQuery akan otomatis mengambil skema menggunakan data sumber pendeskripsian mandiri. Saat membuat definisi tabel, Anda tidak perlu memberikan file skema atau definisi skema inline.
Anda dapat membuat file definisi tabel untuk data ekspor Datastore dan Firestore yang disimpan di Cloud Storage:
Gunakan perintah
bq mkdef
untuk membuat definisi tabel. Anda tidak perlu menggunakan flag--noautodetect
dengan file cadangan Datastore atau Firestore. Deteksi otomatis skema dinonaktifkan untuk jenis file ini. Perintahmkdef
akan menghasilkan file definisi tabel dalam format JSON. Contoh berikut akan membuat definisi tabel dan menulis output ke file:/tmp/file_name
.bq mkdef \ --source_format=DATASTORE_BACKUP \ "URI" > /tmp/FILE_NAME
Ganti kode berikut:
URI
: Cloud Storage URIFILE_NAME
: nama file definisi tabel
Format sumber
DATASTORE_BACKUP
digunakan untuk Datastore dan Firestore.(Opsional) Buka file definisi tabel di editor teks. Misalnya, perintah
nano /tmp/file_name
akan membuka file di nano. Filenya akan terlihat seperti berikut. Perhatikan bahwa setelan"autodetect"
tidak diperlukan.{ "sourceFormat": "DATASTORE_BACKUP", "sourceUris": [ "gs://URI" ] }
(Opsional) Edit file definisi tabel secara manual untuk mengubah, menambahkan, atau menghapus setelan seperti
maxBadRecords
danignoreUnknownValues
. Tidak ada setelan konfigurasi yang khusus untuk file ekspor Datastore dan Firestore. Untuk informasi selengkapnya, lihatExternalDataConfiguration
dalam referensi API.
Membuat file definisi untuk Bigtable
Saat membuat file definisi tabel untuk Bigtable, Anda akan menghasilkan
file tersebut secara manual dalam format JSON. Penggunaan perintah mkdef
untuk membuat definisi tabel
saat ini tidak didukung untuk sumber data Bigtable.
Deteksi otomatis skema juga tidak didukung untuk Bigtable. Untuk daftar
opsi definisi tabel Bigtable, lihat
BigtableOptions
dalam
referensi REST API.
File definisi tabel JSON untuk Bigtable terlihat seperti berikut. Dengan menggunakan file definisi tabel ini, BigQuery membaca data dari satu grup kolom, yang menafsirkan nilainya sebagai bilangan bulat dengan enkode biner.
{ "sourceFormat": "BIGTABLE", "sourceUris": [ "https://googleapis.com/bigtable/projects/PROJECT_ID/instances/INSTANCE_ID/tables/TABLE_NAME" ], "bigtableOptions": { "columnFamilies" : [ { "familyId": "FAMILY_ID", "type": "INTEGER", "encoding": "BINARY" } ] } }
Ganti kode berikut:
PROJECT_ID
: project yang berisi cluster Bigtable AndaINSTANCE_ID
: ID instance BigtableTABLE_NAME
: nama tabel yang Anda kueriFAMILY_ID
: ID grup kolom
Untuk mengetahui informasi selengkapnya, baca bagian Mengambil URI Bigtable.
Dukungan karakter pengganti untuk file definisi tabel
Jika data dipisahkan menjadi beberapa file, Anda dapat menggunakan karakter pengganti tanda bintang (*) untuk memilih beberapa file. Penggunaan karakter pengganti tanda bintang harus mengikuti aturan berikut:
- Tanda bintang dapat muncul di dalam nama objek atau di akhir nama objek.
- Menggunakan beberapa tanda bintang tidak didukung. Misalnya, jalur
gs://mybucket/fed-*/temp/*.csv
tidak valid. - Penggunaan tanda bintang dengan nama bucket tidak didukung.
Contoh:
Contoh berikut menunjukkan cara memilih semua file di semua folder yang dimulai dengan awalan
gs://mybucket/fed-samples/fed-sample
:gs://mybucket/fed-samples/fed-sample*
Contoh berikut menunjukkan cara memilih file dengan ekstensi
.csv
saja di folder bernamafed-samples
dan subfolderfed-samples
apa pun:gs://mybucket/fed-samples/*.csv
Contoh berikut menunjukkan cara memilih file dengan pola penamaan
fed-sample*.csv
dalam folder bernamafed-samples
. Contoh ini tidak memilih file di subfolderfed-samples
.gs://mybucket/fed-samples/fed-sample*.csv
Saat menggunakan alat command line bq, Anda mungkin perlu meng-escape tanda bintang di beberapa platform.
Jika Anda menggunakan karakter pengganti tanda bintang, masukkan bucket dan nama file dalam tanda kutip. Misalnya,
jika Anda memiliki dua file bernama fed-sample000001.csv
dan
fed-sample000002.csv
, lalu Anda ingin menggunakan tanda bintang untuk memilih keduanya,
URI bucket akan menjadi "gs://mybucket/fed-sample*"
.
Karakter pengganti *
tidak diizinkan saat membuat file definisi tabel
untuk sumber data berikut:
- Bigtable. Untuk data Bigtable, hanya satu sumbe data yang dapat ditentukan. Nilai URI harus berupa URL HTTPS yang valid untuk tabel Bigtable.
- Datastore atau Firestore. Ekspor
Datastore atau Firestore yang disimpan di
Cloud Storage. Untuk cadangan
Datastore, hanya satu sumber data yang dapat ditentukan. Nilai URI harus diakhiri dengan
.backup_info
atau.export_metadata
. - Drive. Data disimpan di Drive.
Langkah selanjutnya
- Pelajari cara membuat kueri data Cloud Storage.
- Pelajari cara membuat kueri data Drive.
- Pelajari cara membuat kueri data Bigtable.