Memecahkan masalah error skema

Dokumen ini membantu Anda mendiagnosis dan menyelesaikan error HTTP 400 Bad Request yang terjadi saat Anda mengubah skema tabel BigQuery atau saat Anda menentukan atau memuat struktur skema bertingkat yang dalam. Untuk mengetahui informasi tentang cara menggunakan tampilan INFORMATION_SCHEMA untuk memecahkan masalah performa BigQuery, lihat Memecahkan masalah dengan skema informasi.

Memecahkan masalah error ketidakcocokan skema

BigQuery menampilkan error Provided Schema does not match Table (reason: invalid) jika salah satu operasi berikut menyediakan skema yang bertentangan dengan skema tabel target yang ada:

  • Tugas pemuatan
  • Tugas kueri dengan tabel tujuan
  • Tugas penyalinan
  • Pernyataan DDL ALTER TABLE
  • Pembaruan metadata tabel (tables.update atau tables.patch)

Untuk mengidentifikasi penyebab dan penyelesaian spesifik, cocokkan pesan error Anda dengan salah satu skenario berikut.

Kolom tidak ada dalam skema baru

Pesan error

Provided Schema does not match Table PROJECT_ID:DATASET.TABLE. Field FIELD_NAME is missing in new schema

Diagnosis

Salah satu operasi berikut memberikan definisi skema yang menghilangkan satu atau beberapa kolom yang sudah ada di tabel tujuan:

  • Tugas pemuatan
  • Operasi tulis DataFrame
  • Panggilan API tables.update atau tables.patch

Resolusi

BigQuery tidak mengizinkan penghapusan kolom secara implisit dengan menghilangkannya dari payload skema API atau konfigurasi tugas pemuatan. Untuk mengatasi error ini, lakukan salah satu tindakan berikut:

  • Perbarui pipeline atau permintaan API Anda sehingga skema yang disediakan menyertakan semua kolom yang ada dalam tabel target.

  • Jika Anda ingin menghapus kolom dari tabel, jalankan pernyataan DDL DROP COLUMN, bukan menghilangkan kolom dari permintaan pemuatan atau patch:

    ALTER TABLE `PROJECT_ID.DATASET.TABLE`
DROP COLUMN FIELD_NAME;

    Ganti kode berikut:

    • PROJECT_ID: ID project yang berisi tabel.
    • DATASET: nama set data yang berisi tabel.
    • TABLE: nama tabel.
    • FIELD_NAME: nama kolom yang akan dihapus.

Jenis kolom telah berubah

Pesan error

Provided Schema does not match Table PROJECT_ID:DATASET.TABLE. Field FIELD_NAME has changed type from EXISTING_TYPE to NEW_TYPE

Diagnosis

Permintaan Anda mencoba mengubah jenis data kolom yang ada (misalnya, dari STRING menjadi INT64) di tempat selama tugas pemuatan atau pembaruan skema.

Resolusi

Untuk mengatasi error ini, lakukan salah satu tindakan berikut:

  • Jika perubahan jenis adalah konversi jenis data kolom yang didukung (seperti INT64 ke NUMERIC, INT64 ke FLOAT64, atau NUMERIC ke BIGNUMERIC), gunakan pernyataan DDL ALTER TABLE ... ALTER COLUMN:

    ALTER TABLE `PROJECT_ID.DATASET.TABLE`
ALTER COLUMN FIELD_NAME SET DATA TYPE NEW_TYPE;

    Ganti kode berikut:

    • PROJECT_ID: ID project yang berisi tabel.
    • DATASET: nama set data yang berisi tabel.
    • TABLE: nama tabel.
    • FIELD_NAME: nama kolom yang akan diubah.
    • NEW_TYPE: jenis data target.

  • Jika konversi jenis tidak didukung di tempat, buat kueri data yang ada dengan ekspresi CAST eksplisit dan tulis hasilnya ke tabel baru atau timpa tabel yang ada. Untuk mengetahui informasi selengkapnya, lihat Mengubah jenis data kolom.

Mode kolom telah berubah

Pesan error

Provided Schema does not match Table PROJECT_ID:DATASET.TABLE. Field FIELD_NAME has changed mode from EXISTING_MODE to NEW_MODE

Diagnosis

Permintaan Anda mencoba mengubah mode kolom yang tidak didukung (misalnya, mengubah NULLABLE menjadi REQUIRED atau REPEATED menjadi NULLABLE). Error ini juga terjadi jika Anda menggunakan definisi skema inline di alat command line bq saat melonggarkan kolom REQUIRED pada tabel yang berisi kolom REPEATED, karena definisi skema inline di alat command line bq tidak mendukung pengubahan tabel dengan kolom REPEATED.

Resolusi

Satu-satunya perubahan mode yang didukung oleh update skema BigQuery di tempat adalah melonggarkan mode kolom dari REQUIRED menjadi NULLABLE. Untuk mengatasi error ini, lakukan salah satu tindakan berikut:

  • Jika Anda melonggarkan kolom dari REQUIRED ke NULLABLE, jalankan pernyataan DDL ALTER TABLE ... ALTER COLUMN ... DROP NOT NULL di GoogleSQL, atau berikan file skema JSON jika Anda memperbarui skema dengan perintah bq update atau metode API tables.patch. Untuk mengetahui petunjuknya, lihat Mengubah mode kolom.
  • Untuk mengubah mode kolom dari NULLABLE menjadi REQUIRED atau dari REPEATED menjadi NULLABLE, buat tabel baru dengan skema yang diperbarui, lalu salin atau muat data ke dalam tabel baru. Untuk mengetahui petunjuknya, lihat Mengubah skema tabel.

Tidak dapat menambahkan kolom

Pesan error

Provided Schema does not match Table PROJECT_ID:DATASET.TABLE. Cannot add fields (field: FIELD_NAME)

Diagnosis

Tugas pemuatan atau tugas kueri menyertakan kolom (FIELD_NAME) yang tidak ada dalam tabel tujuan, dan penambahan skema tidak diaktifkan dalam konfigurasi tugas.

Resolusi

Aktifkan penambahan skema pada tugas pemuatan atau kueri:

  • Di REST API atau library klien, sertakan ALLOW_FIELD_ADDITION di properti schemaUpdateOptions konfigurasi tugas pemuatan atau kueri Anda.
  • Di alat command line bq, teruskan flag --schema_update_option=ALLOW_FIELD_ADDITION.
  • Atau, tambahkan kolom sebelum menjalankan tugas menggunakan ALTER TABLE ... ADD COLUMN.

Tidak dapat menambahkan kolom wajib diisi ke skema yang ada

Pesan error

Provided Schema does not match Table PROJECT_ID:DATASET.TABLE. Cannot add required fields to an existing schema. (field: FIELD_NAME)

Diagnosis

Permintaan Anda menambahkan kolom baru ke tabel yang ada dengan mode kolom yang ditetapkan ke REQUIRED (NOT NULL). Karena baris yang ada dalam tabel akan menerima nilai NULL untuk kolom yang baru ditambahkan, BigQuery menolak penambahan kolom REQUIRED secara langsung melalui update skema.

Resolusi

Untuk mengatasi error ini, lakukan salah satu tindakan berikut:

  • Tambahkan kolom baru dengan mode NULLABLE, bukan REQUIRED, lalu jalankan pernyataan UPDATE DML untuk mengisi nilai baris yang ada.

  • Untuk menambahkan kolom dan menetapkan nilai default, selesaikan langkah-langkah berikut:

    1. Tambahkan kolom sebagai kolom NULLABLE.
    2. Tetapkan nilai default kolom sehingga penyisipan di masa mendatang akan menerima nilai secara otomatis.

    3. Perbarui baris yang ada untuk mengisi nilai default:

      ALTER TABLE `PROJECT_ID.DATASET.TABLE`
ADD COLUMN FIELD_NAME DATA_TYPE;

ALTER TABLE `PROJECT_ID.DATASET.TABLE`
ALTER COLUMN FIELD_NAME SET DEFAULT DEFAULT_EXPRESSION;

UPDATE `PROJECT_ID.DATASET.TABLE`
SET FIELD_NAME = DEFAULT_EXPRESSION
WHERE TRUE;

      Ganti kode berikut:

      • PROJECT_ID: ID project yang berisi tabel.
      • DATASET: nama set data yang berisi tabel.
      • TABLE: nama tabel.
      • FIELD_NAME: nama kolom baru.
      • DATA_TYPE: jenis data kolom.
      • DEFAULT_EXPRESSION: ekspresi nilai default untuk kolom.

Kolom sudah ada dalam skema

Pesan error

Field FIELD_NAME already exists in schema

Diagnosis

Skema yang disediakan dalam permintaan API, file skema JSON, atau header file sumber (seperti CSV atau Parquet) berisi nama kolom duplikat. Nama kolom di BigQuery tidak peka huruf besar/kecil, sehingga menentukan Field_A dan field_a dalam skema yang sama akan memicu error ini.

Resolusi

Periksa skema sumber dan hapus atau ganti nama kolom duplikat, termasuk konflik nama yang tidak peka huruf besar/kecil.

Memperbarui pemeriksaan kolom tidak didukung

Pesan error

Provided Schema does not match Table PROJECT_ID:DATASET.TABLE. Invalid schema update. Updating field collation is not supported. Field FIELD_NAME has changed collation from "EXISTING_COLLATION" to "NEW_COLLATION"

Diagnosis

Anda tidak dapat mengubah atau menghapus spesifikasi pengurutan kolom yang ada selama update skema. Error ini biasanya terjadi saat aplikasi mengambil skema tabel, mengubah kolom lain, dan menulis kembali skema menggunakan versi library klien lama yang tidak mempertahankan properti kolom collation (mengirim "", bukan "und:ci").

Resolusi

Untuk mengatasi error ini, lakukan hal berikut:

  • Upgrade library klien BigQuery Anda ke versi terbaru agar atribut collation yang ada dipertahankan saat membaca dan mem-patch metadata tabel.
  • Jika Anda membuat payload skema JSON secara manual, pastikan properti collation pada kolom yang ada cocok dengan skema tabel saat ini.

Mempersempit parameter jenis tidak kompatibel

Pesan error

Provided Schema does not match Table PROJECT_ID:DATASET.TABLE. Narrowing type parameters is not compatible

Diagnosis

Pernyataan ALTER TABLE ... ALTER COLUMN ... SET DATA TYPE Anda mencoba mengurangi panjang, presisi, atau skala maksimum jenis data berparameter—misalnya, mengubah STRING(100) menjadi STRING(50) atau mengurangi parameter NUMERIC(P, S).

Resolusi

BigQuery hanya mengizinkan perluasan parameter jenis pada kolom yang ada (seperti meningkatkan STRING(50) menjadi STRING(100)). Untuk menerapkan parameter jenis yang lebih sempit, buat tabel baru yang ditentukan dengan parameter jenis yang lebih sempit dan salin atau muat data ke tabel baru menggunakan kueri SELECT yang membuat nilai sesuai dengan jenis yang lebih sempit (misalnya, LEFT(FIELD_NAME, 50) untuk kolom STRING). Menulis nilai STRING atau BYTES yang lebih panjang dari panjang maksimum kolom, atau nilai NUMERIC dengan digit lebih banyak daripada yang diizinkan oleh presisinya, akan menampilkan error. Nilai NUMERIC dengan digit desimal lebih banyak daripada skala kolom akan dibulatkan. Untuk mengetahui informasi selengkapnya, lihat Mengubah skema tabel.

Penambahan kolom dengan nilai default tidak didukung

Pesan error

Provided Schema does not match Table PROJECT_ID:DATASET.TABLE. Add field with default value to an existing table schema is not supported; Field: FIELD_NAME. ...

Diagnosis

Tugas pemuatan atau permintaan API tables.patch atau tables.update Anda mencoba menambahkan kolom baru ke tabel yang ada sambil menentukan defaultValueExpression dalam payload skema API. Anda tidak dapat menambahkan kolom baru dengan nilai default ke tabel yang ada dalam satu update skema API.

Resolusi

Daripada menentukan defaultValueExpression saat Anda menambahkan kolom dalam permintaan API, tambahkan kolom terlebih dahulu, lalu tetapkan nilai defaultnya (untuk mengetahui informasi selengkapnya, lihat Batasan):

  • Jika Anda belum menambahkan kolom, jalankan pernyataan berikut, lalu lanjutkan pemuatan tanpa defaultValueExpression:

    ALTER TABLE `PROJECT_ID.DATASET.TABLE`
ADD COLUMN FIELD_NAME DATA_TYPE;

ALTER TABLE `PROJECT_ID.DATASET.TABLE`
ALTER COLUMN FIELD_NAME SET DEFAULT DEFAULT_EXPRESSION;

UPDATE `PROJECT_ID.DATASET.TABLE`
SET FIELD_NAME = DEFAULT_EXPRESSION
WHERE TRUE;

    Ganti kode berikut:

    • PROJECT_ID: ID project yang berisi tabel.
    • DATASET: nama set data yang berisi tabel.
    • TABLE: nama tabel.
    • FIELD_NAME: nama kolom baru.
    • DATA_TYPE: jenis data kolom.
    • DEFAULT_EXPRESSION: ekspresi nilai default untuk kolom.

  • Jika Anda sudah menambahkan kolom dengan mengirim ulang permintaan tanpa defaultValueExpression, jalankan hanya pernyataan ALTER COLUMN ... SET DEFAULT dan UPDATE dari contoh sebelumnya.

Memperbarui atribut kolom identitas yang ada tidak didukung

Pesan error

Provided Schema does not match Table PROJECT_ID:DATASET.TABLE. Updating an existing identity column's attributes is not supported. Field FIELD_NAME already has identity column info.

Diagnosis

Permintaan Anda mencoba mengubah atribut kolom identitas yang ada melalui update skema atau patch API.

Resolusi

Properti kolom identitas tidak dapat diubah di tempat setelah pembuatan. Biarkan definisi kolom identitas yang ada tidak berubah dalam payload update skema Anda, atau buat tabel baru dengan konfigurasi kolom identitas yang telah diupdate dan salin atau muat data ke dalam tabel baru. Untuk mengetahui petunjuknya, lihat Mengubah skema tabel.

Perubahan kolom yang tidak kompatibel dalam kolom RECORD

Pesan error

Provided Schema does not match Table PROJECT_ID:DATASET.TABLE. Incompatible field change within RECORD column

Diagnosis

Pernyataan ALTER TABLE ... ALTER COLUMN ... SET DATA TYPE Anda menentukan jenis STRUCT yang tidak kompatibel dengan jenis kolom yang ada. Misalnya, jenis baru menambahkan atau menghapus subkolom, mengubah subkolom menjadi jenis yang tidak didukung, atau mempersempit parameter jenis subkolom.

Resolusi

Bandingkan jenis STRUCT dalam pernyataan ALTER TABLE Anda dengan skema kolom yang ada, lalu lakukan salah satu tindakan berikut:

  • Pertahankan subkolom yang sama dalam urutan yang sama, dan ubah jenis subkolom hanya dengan cara yang didukung untuk perubahan jenis data kolom.
  • DDL tidak dapat menambahkan subkolom bertingkat ke kolom RECORD yang ada. Sebagai gantinya, perbarui skema menggunakan file skema JSON dengan bq update atau metode tables.patch. Untuk mengetahui informasi selengkapnya, lihat Menambahkan kolom bertingkat ke kolom RECORD.
  • Untuk menghapus atau merestrukturisasi subkolom bertingkat, lihat Mengubah jenis kolom bertingkat.

Batas maksimum skema fisik yang berbeda telah tercapai

Pesan error

Provided Schema does not match Table PROJECT_ID:DATASET.TABLE. Maximum limit on diverging physical schemas reached.

Diagnosis

Modifikasi skema tabel tertentu, seperti menghapus atau mengganti nama kolom, dapat menyebabkan tabel memiliki skema logis yang identik di API, meskipun memiliki representasi skema fisik yang mendasarinya berbeda. Saat Anda menyalin data ke tabel tujuan di terlalu banyak versi skema fisik yang berbeda, tugas penyalinan tabel dapat gagal dengan error ini. Untuk mengetahui informasi selengkapnya, lihat Batasan dalam menyalin tabel.

Resolusi

Gunakan pernyataan DDL CREATE TABLE LIKE untuk membuat ulang tabel tujuan sehingga representasi skema fisiknya cocok dengan skema tabel sumber, lalu salin atau sisipkan data:

CREATE OR REPLACE TABLE `PROJECT_ID.DATASET.DESTINATION_TABLE`
LIKE `PROJECT_ID.DATASET.SOURCE_TABLE`;

INSERT INTO `PROJECT_ID.DATASET.DESTINATION_TABLE`
SELECT * FROM `PROJECT_ID.DATASET.SOURCE_TABLE`;

Ganti kode berikut:

  • PROJECT_ID: ID project yang berisi tabel.
  • DATASET: nama set data yang berisi tabel.
  • DESTINATION_TABLE: nama tabel tujuan yang akan dibuat ulang.
  • SOURCE_TABLE: nama tabel sumber.

Memecahkan masalah error batas bertingkat skema, file, dan rutinitas

BigQuery menerapkan kedalaman bertingkat maksimum 15 level untuk kolom STRUCT (RECORD), file pemuatan terstruktur, serta argumen dan jenis nilai yang ditampilkan dari rutinitas bertingkat. Jika melebihi batas 15 level ini, error HTTP 400 Bad Request akan ditampilkan dengan salah satu pesan berikut (dengan MAX_DEPTH dan MAX_LEVEL adalah 15). Untuk error yang disebabkan oleh melebihi batas bertingkat 16 level pada tampilan logis atau fungsi yang ditentukan pengguna persisten (UDF), lihat Terlalu banyak tampilan bertingkat atau fungsi yang ditentukan pengguna persisten.

Pesan error

  • Schema nested too deeply.
  • Schema nested too deeply for field FIELD_NAME, maximum allowed depth is MAX_DEPTH.
  • Field 'FIELD_NAME' is nested too deeply. It has definition level LEVEL while maximum allowed definition level is MAX_LEVEL.
  • Schema nested too deeply, at least LEVEL compared to the maximum allowed level of 15.
  • Routine TYPE_DESCRIPTION nested too deeply; max allowed depth: MAX_DEPTH

Diagnosis

Kolom jenis STRUCT (RECORD) dapat berisi kolom RECORD bertingkat hingga kedalaman maksimum 15 level, terlepas dari apakah kolom tersebut skalar (NULLABLE atau REQUIRED) atau berbasis array (REPEATED). Demikian pula, tugas pemuatan JSON, Parquet, dan Avro serta tabel eksternal menerapkan batas bertingkat saat mengurai struktur bertingkat. Untuk file Parquet, batasnya dinyatakan sebagai tingkat definisi maksimum dan tingkat pengulangan maksimum.

Dalam error rutinitas, TYPE_DESCRIPTION mengidentifikasi jenis bertingkat: argument type, return type, atau return table type.

Resolusi

Batas ini tidak dapat ditambah. Untuk mengatasi error ini, lakukan salah satu tindakan berikut:

  • Ratakan definisi jenis skema atau rutinitas. Pisahkan hierarki STRUCT atau ARRAY yang bertingkat dalam skema tabel atau argumen rutinitas dan jenis nilai yang ditampilkan menjadi tabel terkait yang terpisah dan gabungkan pada waktu kueri, atau promosikan atribut bertingkat ke kolom tingkat yang lebih tinggi.
  • Gunakan jenis data JSON bawaan. Jika data Anda memerlukan lebih dari 15 tingkat bertingkat, simpan subtree bertingkat dalam kolom berjenis JSON (atau STRING). Kolom JSON disimpan sebagai satu kolom dalam skema tabel—menghindari batas skema RECORD 15 tingkat—sekaligus memungkinkan Anda mengekstrak jalur bertingkat dalam pada waktu kueri menggunakan operator dan fungsi akses kolom JSON.
  • Praproses file input sebelum dimuat. Jika error terjadi selama tugas pemuatan dari file JSON, Parquet, atau Avro di Cloud Storage, tambahkan langkah pra-pemrosesan upstream untuk meratakan atau melakukan serialisasi struktur yang lebih dalam dari 15 level sebelum memuatnya ke BigQuery.