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
Menggunakan skema inline
Menggunakan file skema JSON

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. Perintah mkdef 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 Anda
- FILE_NAME: nama file definisi tabel
- URI: Cloud Storage URI
  
  Misalnya, 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 ke true.

{
"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 dan ignoreUnknownValues. Tidak ada setelan konfigurasi yang khusus untuk file sumber JSON, tetapi ada setelan yang berlaku untuk CSV dan file Google Spreadsheet. Untuk informasi selengkapnya, lihat ExternalDataConfiguration 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. Perintah mkdef 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 Anda
- FILE_NAME: nama file definisi tabel
- URI: URI Drive
  
  Misalnya, 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 ke true.
```
{
"autodetect": true,
"sourceFormat": "GOOGLE_SHEETS",
"sourceUris": [
  "URI"
]
}
```
(Opsional) Edit file definisi tabel secara manual untuk mengubah, menambahkan, atau menghapus setelan umum seperti maxBadRecords dan ignoreUnknownValues. Tidak ada setelan konfigurasi yang khusus untuk file sumber JSON, tetapi ada setelan yang berlaku untuk CSV dan file Google Spreadsheet. Untuk informasi selengkapnya, lihat ExternalDataConfiguration 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 parameter range 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. Perintah mkdef 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 sumber
- URI: Cloud Storage URI atau URI Drive
  
  Misalnya, gs://mybucket/myfile untuk Cloud Storage atau https://drive.google.com/open?id=123ABCD123AbcD123Abcd untuk Drive.
- FIELD:DATA_TYPE,FIELD:DATA_TYPE: definisi skema
  
  Misalnya, 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 dan ignoreUnknownValues. Tidak ada setelan konfigurasi yang khusus untuk file sumber JSON, tetapi ada setelan yang berlaku untuk CSV dan file Google Spreadsheet. Untuk informasi selengkapnya, lihat ExternalDataConfiguration 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. Perintah mkdef 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 Anda
- FILE_NAME: nama file definisi tabel
- URI: Cloud Storage URI
  
  Misalnya, 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 dan ignoreUnknownValues. Tidak ada setelan konfigurasi yang khusus untuk file sumber JSON, tetapi ada setelan yang berlaku untuk CSV dan file Google Spreadsheet. Untuk informasi selengkapnya, lihat ExternalDataConfiguration 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. Perintah mkdef 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 sumber
- URI: URI Drive
  
  Misalnya, https://drive.google.com/open?id=123ABCD123AbcD123Abcd.
- PATH_TO_SCHEMA_FILE: lokasi file skema JSON di komputer lokal Anda
- FILE_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 dan ignoreUnknownValues. Tidak ada setelan konfigurasi yang khusus untuk file sumber JSON, tetapi ada setelan yang berlaku untuk CSV dan file Google Spreadsheet. Untuk informasi selengkapnya, lihat ExternalDataConfiguration 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 parameter range 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 sumber
- URI: Cloud Storage URI atau URI Drive
  
  Misalnya, gs://mybucket/myfile untuk Cloud Storage atau https://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 dan ignoreUnknownValues. Untuk informasi selengkapnya, lihat ExternalDataConfiguration 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. Perintah mkdef 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 URI
- FILE_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 dan ignoreUnknownValues. Tidak ada setelan konfigurasi yang khusus untuk file ekspor Datastore dan Firestore. Untuk informasi selengkapnya, lihat ExternalDataConfiguration 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 Anda
INSTANCE_ID: ID instance Bigtable
TABLE_NAME: nama tabel yang Anda kueri
FAMILY_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 bernama fed-samples dan subfolder fed-samples apa pun:
```
gs://mybucket/fed-samples/*.csv
```
Contoh berikut menunjukkan cara memilih file dengan pola penamaan fed-sample*.csv dalam folder bernama fed-samples. Contoh ini tidak memilih file di subfolder fed-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.