Schemafehler beheben

In diesem Dokument wird beschrieben, wie Sie HTTP-400 Bad Request-Fehler diagnostizieren und beheben, die beim Ändern von BigQuery-Tabellenschemas oder beim Definieren oder Laden tief verschachtelter Schemastrukturen auftreten. Informationen zur Verwendung von INFORMATION_SCHEMA-Ansichten zur Fehlerbehebung bei der BigQuery-Leistung finden Sie unter Fehlerbehebung mit Informationsschema.

Fehler aufgrund von Schemaabweichungen beheben

BigQuery gibt den Fehler Provided Schema does not match Table (reason: invalid) zurück, wenn einer der folgenden Vorgänge ein Schema bereitstellt, das mit dem vorhandenen Schema der Zieltabelle in Konflikt steht:

  • Ein Ladejob
  • Ein Abfragejob mit einer Zieltabelle
  • Ein Kopierjob
  • Eine ALTER TABLE-DDL-Anweisung
  • Eine Aktualisierung der Tabellenmetadaten (tables.update oder tables.patch)

Um die genaue Ursache und Lösung zu ermitteln, ordnen Sie Ihre Fehlermeldung einem der folgenden Szenarien zu.

Feld fehlt im neuen Schema

Fehlermeldung

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

Diagnose

Einer der folgenden Vorgänge stellt eine Schemadefinition bereit, in der eine oder mehrere Spalten weggelassen werden, die bereits in der Zieltabelle vorhanden sind:

  • Ein Ladejob
  • Ein DataFrame-Schreibvorgang
  • Ein tables.update- oder tables.patch-API-Aufruf

Lösung

In BigQuery ist es nicht zulässig, Spalten implizit zu löschen, indem sie aus einer API-Schemanutzlast oder einer Ladejobkonfiguration weggelassen werden. Führen Sie einen der folgenden Schritte aus, um diesen Fehler zu beheben:

  • Aktualisieren Sie Ihre Pipeline oder API-Anfrage, sodass das bereitgestellte Schema alle vorhandenen Spalten in der Zieltabelle enthält.

  • Wenn Sie die Spalte aus der Tabelle entfernen möchten, führen Sie eine DDL-Anweisung des Typs DROP COLUMN aus, anstatt die Spalte in einer Lade- oder Patchanfrage wegzulassen:

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

    Ersetzen Sie Folgendes:

    • PROJECT_ID: die ID des Projekts, das die Tabelle enthält.
    • DATASET: der Name des Datasets, das die Tabelle enthält.
    • TABLE: der Name der Tabelle.
    • FIELD_NAME: Der Name der zu löschenden Spalte.

Feldtyp wurde geändert

Fehlermeldung

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

Diagnose

In Ihrer Anfrage wird versucht, den Datentyp einer vorhandenen Spalte (z. B. von STRING in INT64) während eines Ladejobs oder einer Schemaaktualisierung zu ändern.

Lösung

Führen Sie einen der folgenden Schritte aus, um diesen Fehler zu beheben:

  • Wenn die Typänderung eine unterstützte Konvertierung des Spaltendatentyps ist (z. B. INT64 in NUMERIC, INT64 in FLOAT64 oder NUMERIC in BIGNUMERIC), verwenden Sie eine ALTER TABLE ... ALTER COLUMN-DDL-Anweisung:

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

    Ersetzen Sie Folgendes:

    • PROJECT_ID: die ID des Projekts, das die Tabelle enthält.
    • DATASET: der Name des Datasets, das die Tabelle enthält.
    • TABLE: der Name der Tabelle.
    • FIELD_NAME: der Name der zu ändernden Spalte.
    • NEW_TYPE: der Zieldatentyp.

  • Wenn die Typkonvertierung nicht direkt unterstützt wird, fragen Sie die vorhandenen Daten mit einem expliziten CAST-Ausdruck ab und schreiben Sie die Ergebnisse in eine neue Tabelle oder überschreiben Sie die vorhandene Tabelle. Weitere Informationen finden Sie unter Datentyp einer Spalte ändern.

Feldmodus wurde geändert

Fehlermeldung

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

Diagnose

Ihre Anfrage versucht, eine nicht unterstützte Änderung des Spaltenmodus vorzunehmen (z. B. Änderung von NULLABLE in REQUIRED oder von REPEATED in NULLABLE). Dieser Fehler tritt auch auf, wenn Sie eine Inline-Schemadefinition im bq-Befehlszeilentool verwenden, um eine REQUIRED-Spalte in einer Tabelle mit REPEATED-Spalten zu lockern, da Inline-Schemadefinitionen im bq-Befehlszeilentool das Ändern von Tabellen mit REPEATED-Spalten nicht unterstützen.

Lösung

Die einzige Modusänderung, die von BigQuery-Schemaaktualisierungen unterstützt wird, ist die Lockerung des Modus einer Spalte von REQUIRED zu NULLABLE. Führen Sie einen der folgenden Schritte aus, um diesen Fehler zu beheben:

  • Wenn Sie eine Spalte von REQUIRED auf NULLABLE lockern, führen Sie eine ALTER TABLE ... ALTER COLUMN ... DROP NOT NULL-DDL-Anweisung in GoogleSQL aus oder stellen Sie eine JSON-Schemadatei bereit, wenn Sie das Schema mit dem Befehl bq update oder der API-Methode tables.patch aktualisieren. Eine Anleitung finden Sie unter Modus einer Spalte ändern.
  • Wenn Sie den Modus einer Spalte von NULLABLE in REQUIRED oder von REPEATED in NULLABLE ändern möchten, erstellen Sie eine neue Tabelle mit dem aktualisierten Schema und kopieren oder laden Sie die Daten in die neue Tabelle. Eine Anleitung finden Sie unter Tabellenschemas ändern.

Felder können nicht hinzugefügt werden

Fehlermeldung

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

Diagnose

Ein Lade- oder Abfragejob enthält eine Spalte (FIELD_NAME), die in der Zieltabelle nicht vorhanden ist, und das Hinzufügen von Schemas ist in der Jobkonfiguration nicht aktiviert.

Lösung

Aktivieren Sie das Hinzufügen von Schemas für den Lade- oder Abfragejob:

  • Fügen Sie in der REST API oder in Clientbibliotheken ALLOW_FIELD_ADDITION in das Attribut schemaUpdateOptions der Konfiguration Ihres Lade- oder Abfragejobs ein.
  • Übergeben Sie im bq-Befehlszeilentool das Flag --schema_update_option=ALLOW_FIELD_ADDITION.
  • Alternativ können Sie die Spalte vor dem Ausführen des Jobs mit ALTER TABLE ... ADD COLUMN hinzufügen.

Erforderliche Felder können einem vorhandenen Schema nicht hinzugefügt werden

Fehlermeldung

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

Diagnose

Mit Ihrer Anfrage wird einer vorhandenen Tabelle eine neue Spalte hinzugefügt, wobei der Spaltenmodus auf REQUIRED (NOT NULL) festgelegt ist. Da vorhandene Zeilen in der Tabelle NULL-Werte für die neu hinzugefügte Spalte erhalten würden, lehnt BigQuery das Hinzufügen von REQUIRED-Spalten direkt über Schemaaktualisierungen ab.

Lösung

Führen Sie einen der folgenden Schritte aus, um diesen Fehler zu beheben:

  • Fügen Sie die neue Spalte mit dem Modus NULLABLE anstelle von REQUIRED hinzu und führen Sie dann eine DML-UPDATE-Anweisung aus, um Werte für vorhandene Zeilen einzufügen.

  • So fügen Sie die Spalte hinzu und weisen einen Standardwert zu:

    1. Fügen Sie die Spalte als NULLABLE-Spalte hinzu.
    2. Legen Sie den Standardwert der Spalte fest, damit zukünftige Einfügungen automatisch einen Wert erhalten.

    3. Aktualisieren Sie vorhandene Zeilen, um den Standardwert einzufügen:

      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;

      Ersetzen Sie Folgendes:

      • PROJECT_ID: die ID des Projekts, das die Tabelle enthält.
      • DATASET: der Name des Datasets, das die Tabelle enthält.
      • TABLE: der Name der Tabelle.
      • FIELD_NAME: Der Name der neuen Spalte.
      • DATA_TYPE: der Datentyp der Spalte.
      • DEFAULT_EXPRESSION: Der Standardwertausdruck für die Spalte.

Feld ist bereits im Schema vorhanden

Fehlermeldung

Field FIELD_NAME already exists in schema

Diagnose

Das in der API-Anfrage, der JSON-Schemadatei oder dem Header der Quelldatei (z. B. CSV oder Parquet) angegebene Schema enthält doppelte Spaltennamen. Bei Spaltennamen in BigQuery wird die Groß-/Kleinschreibung nicht berücksichtigt. Wenn Sie also sowohl Field_A als auch field_a im selben Schema angeben, wird dieser Fehler ausgelöst.

Lösung

Prüfen Sie das Quellschema und entfernen oder benennen Sie doppelte Spaltennamen um, einschließlich aller Namenskonflikte, bei denen die Groß-/Kleinschreibung nicht berücksichtigt wird.

Das Aktualisieren der Feld-Sortierung wird nicht unterstützt

Fehlermeldung

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"

Diagnose

Sie können die Sortierspezifikation einer vorhandenen Spalte während einer Schemaaktualisierung nicht ändern oder entfernen. Dieser Fehler tritt häufig auf, wenn eine Anwendung das Schema einer Tabelle abruft, ein anderes Feld ändert und das Schema mit einer älteren Version der Clientbibliothek zurückschreibt, die die Feldeigenschaft collation nicht beibehält ("" wird anstelle von "und:ci" gesendet).

Lösung

So beheben Sie diesen Fehler:

  • Aktualisieren Sie Ihre BigQuery-Clientbibliothek auf die aktuelle Version, damit vorhandene collation-Attribute beim Lesen und Patchen von Tabellenmetadaten beibehalten werden.
  • Wenn Sie JSON-Schemanutzlasten manuell erstellen, achten Sie darauf, dass das Attribut collation für vorhandene Spalten mit dem aktuellen Schema der Tabelle übereinstimmt.

Das Einschränken von Typparametern ist nicht kompatibel

Fehlermeldung

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

Diagnose

Ihre ALTER TABLE ... ALTER COLUMN ... SET DATA TYPE-Anweisung versucht, die maximale Länge, Genauigkeit oder Skalierung eines parametrisierten Datentyps zu reduzieren, z. B. durch Ändern von STRING(100) in STRING(50) oder durch Reduzieren von NUMERIC(P, S)-Parametern.

Lösung

In BigQuery können nur Typparameter für eine vorhandene Spalte erweitert werden (z. B. von STRING(50) auf STRING(100)). Wenn Sie engere Typparameter erzwingen möchten, erstellen Sie eine neue Tabelle mit dem engeren Typparameter und kopieren oder laden Sie die Daten mit einer SELECT-Abfrage in die neue Tabelle, damit die Werte dem engeren Typ entsprechen (z. B. LEFT(FIELD_NAME, 50) für eine STRING-Spalte). Wenn Sie einen STRING- oder BYTES-Wert schreiben, der länger als die maximale Länge der Spalte ist, oder einen NUMERIC-Wert mit mehr Ziffern, als die Genauigkeit zulässt, wird ein Fehler zurückgegeben. NUMERIC-Werte mit mehr Dezimalstellen als die Skalierung der Spalte werden gerundet. Weitere Informationen finden Sie unter Tabellenschemas ändern.

Das Hinzufügen eines Felds mit einem Standardwert wird nicht unterstützt

Fehlermeldung

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

Diagnose

Ihr Ladejob oder Ihre tables.patch- oder tables.update-API-Anfrage versucht, einer vorhandenen Tabelle eine neue Spalte hinzuzufügen, während in der API-Schemanutzlast defaultValueExpression angegeben ist. Sie können einer vorhandenen Tabelle in einer einzelnen API-Schemaaktualisierung keine neue Spalte mit einem Standardwert hinzufügen.

Lösung

Anstatt defaultValueExpression anzugeben, wenn Sie die Spalte in der API-Anfrage hinzufügen, fügen Sie die Spalte zuerst hinzu und legen Sie dann ihren Standardwert fest. Weitere Informationen finden Sie unter Einschränkungen:

  • Wenn Sie die Spalte noch nicht hinzugefügt haben, führen Sie die folgenden Anweisungen aus und setzen Sie dann die Ladevorgänge ohne defaultValueExpression fort:

    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;

    Ersetzen Sie Folgendes:

    • PROJECT_ID: die ID des Projekts, das die Tabelle enthält.
    • DATASET: der Name des Datasets, das die Tabelle enthält.
    • TABLE: der Name der Tabelle.
    • FIELD_NAME: Der Name der neuen Spalte.
    • DATA_TYPE: der Datentyp der Spalte.
    • DEFAULT_EXPRESSION: Der Standardwertausdruck für die Spalte.

  • Wenn Sie die Spalte bereits hinzugefügt haben, indem Sie die Anfrage ohne defaultValueExpression noch einmal gesendet haben, führen Sie nur die Anweisungen ALTER COLUMN ... SET DEFAULT und UPDATE aus dem vorherigen Beispiel aus.

Das Aktualisieren der Attribute einer vorhandenen Identitätsspalte wird nicht unterstützt

Fehlermeldung

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.

Diagnose

In Ihrer Anfrage wird versucht, die Attribute einer vorhandenen Identitätsspalte über eine Schemaaktualisierung oder einen API-Patch zu ändern.

Lösung

Die Attribute von Identitätsspalten können nach dem Erstellen nicht mehr geändert werden. Behalten Sie die vorhandene Definition der Identitätsspalte in der Nutzlast für die Schemaaktualisierung unverändert bei oder erstellen Sie eine neue Tabelle mit der aktualisierten Konfiguration der Identitätsspalte und kopieren oder laden Sie die Daten in die neue Tabelle. Eine Anleitung finden Sie unter Tabellenschemas ändern.

Inkompatible Feldänderung in RECORD-Spalte

Fehlermeldung

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

Diagnose

In Ihrer ALTER TABLE ... ALTER COLUMN ... SET DATA TYPE-Anweisung wird ein STRUCT-Typ angegeben, der nicht mit dem vorhandenen Typ der Spalte kompatibel ist. Beispielsweise werden durch den neuen Typ Unterfelder hinzugefügt oder entfernt, ein Unterfeld wird in einen nicht unterstützten Typ geändert oder die Typparameter eines Unterfelds werden eingeschränkt.

Lösung

Vergleichen Sie den Typ STRUCT in Ihrer ALTER TABLE-Anweisung mit dem vorhandenen Schema der Spalte und führen Sie dann einen der folgenden Schritte aus:

  • Behalten Sie die Unterfelder in derselben Reihenfolge bei und ändern Sie die Unterfeldtypen nur so, wie es für Änderungen des Spaltendatentyps unterstützt wird.
  • Mit DDL können einer vorhandenen RECORD-Spalte keine verschachtelten Unterfelder hinzugefügt werden. Aktualisieren Sie das Schema stattdessen mit einer JSON-Schemadatei mit bq update oder der Methode tables.patch. Weitere Informationen finden Sie unter Verschachtelte Spalte einer RECORD-Spalte hinzufügen.
  • Informationen zum Entfernen oder Umstrukturieren verschachtelter Unterfelder finden Sie unter Verschachtelte Spaltentypen ändern.

Maximale Anzahl abweichender physischer Schemas erreicht

Fehlermeldung

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

Diagnose

Bestimmte Änderungen am Tabellenschema, z. B. das Löschen oder Umbenennen von Spalten, können dazu führen, dass Tabellen in der API identische logische Schemas haben, aber unterschiedliche zugrunde liegende physische Schemadarstellungen. Wenn Sie Daten in eine Zieltabelle mit zu vielen unterschiedlichen physischen Schemaversionen kopieren, kann der Tabellenkopierjob mit diesem Fehler fehlschlagen. Weitere Informationen finden Sie unter Einschränkungen beim Kopieren von Tabellen.

Lösung

Verwenden Sie die DDL-Anweisung CREATE TABLE LIKE, um die Zieltabelle neu zu erstellen, sodass ihre physische Schemadarstellung mit dem Schema der Quelltabelle übereinstimmt. Kopieren Sie dann die Daten oder fügen Sie sie ein:

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`;

Ersetzen Sie Folgendes:

  • PROJECT_ID: die ID des Projekts, das die Tabellen enthält.
  • DATASET: der Name des Datasets, das die Tabellen enthält.
  • DESTINATION_TABLE: der Name der neu zu erstellenden Zieltabelle.
  • SOURCE_TABLE: der Name der Quelltabelle.

Fehler bei Schema-, Datei- und Routineverschachtelungslimits beheben

BigQuery erzwingt eine maximale Verschachtelungstiefe von 15 Ebenen für STRUCT-Spalten (RECORD), strukturierte Ladedateien sowie verschachtelte Routinenargumente und Rückgabetypen. Wenn Sie dieses Limit von 15 Ebenen überschreiten, wird ein HTTP-400 Bad Request-Fehler mit einer der folgenden Meldungen zurückgegeben (wobei MAX_DEPTH und MAX_LEVEL 15 sind). Informationen zu Fehlern, die durch das Überschreiten des Limits von 16 Verschachtelungsebenen für logische Ansichten oder persistente benutzerdefinierte Funktionen (UDFs) verursacht werden, finden Sie unter Zu viele verschachtelte Ansichten oder persistente benutzerdefinierte Funktionen.

Fehlermeldungen beim Dienst zur Datenmigration

  • 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

Diagnose

Spalten vom Typ STRUCT (RECORD) können verschachtelte RECORD-Felder bis zu einer maximalen Tiefe von 15 Ebenen enthalten, unabhängig davon, ob die Felder skalar (NULLABLE oder REQUIRED) oder arraybasiert (REPEATED) sind. Ebenso erzwingen JSON-, Parquet- und Avro-Ladejobs sowie externe Tabellen das Verschachtelungslimit, wenn sie verschachtelte Strukturen parsen. Bei Parquet-Dateien wird das Limit als maximale Definitionsebene und maximale Wiederholungsebene ausgedrückt.

Bei Routinefehlern gibt TYPE_DESCRIPTION den verschachtelten Typ an: argument type, return type oder return table type.

Lösung

Dieses Limit kann nicht erhöht werden. Führen Sie einen der folgenden Schritte aus, um diesen Fehler zu beheben:

  • Schema- oder Routinentypdefinition vereinfachen. Unterteilen Sie tief verschachtelte STRUCT- oder ARRAY-Hierarchien in Ihrem Tabellenschema oder in Ihren Routinenargumenten und Rückgabetypen in separate, verwandte Tabellen und verknüpfen Sie sie bei der Abfrage. Alternativ können Sie tief verschachtelte Attribute in Spalten auf höherer Ebene verschieben.
  • Verwenden Sie den integrierten Datentyp JSON. Wenn Ihre Daten mehr als 15 Verschachtelungsebenen erfordern, speichern Sie die tief verschachtelten Unterbäume in einer Spalte vom Typ JSON (oder STRING). Eine JSON-Spalte wird als einzelne Spalte im Tabellenschema gespeichert. Dadurch wird das Schemalimit von 15 Ebenen für RECORD vermieden. Gleichzeitig können Sie tief verschachtelte Pfade bei der Abfrage mithilfe von JSON-Feldzugriffsoperatoren und -funktionen extrahieren.
  • Eingabedateien vor dem Laden vorverarbeiten. Wenn der Fehler während eines Ladejobs aus JSON-, Parquet- oder Avro-Dateien in Cloud Storage auftritt, fügen Sie einen vorgelagerten Vorverarbeitungsschritt hinzu, um Strukturen mit mehr als 15 Ebenen zu vereinfachen oder zu serialisieren, bevor Sie sie in BigQuery laden.