Risolvi gli errori dello schema

Questo documento ti aiuta a diagnosticare e risolvere gli errori HTTP 400 Bad Request che si verificano quando modifichi gli schemi delle tabelle BigQuery o quando definisci o carichi strutture di schemi con nidificazione profonda. Per informazioni su come utilizzare le viste INFORMATION_SCHEMA per risolvere i problemi relativi alle prestazioni di BigQuery, consulta Risolvi i problemi con Information Schema.

Risolvi gli errori di mancata corrispondenza dello schema

BigQuery restituisce un errore Provided Schema does not match Table (reason: invalid) quando una delle seguenti operazioni fornisce uno schema in conflitto con lo schema esistente della tabella di destinazione:

  • Un job di caricamento
  • Un job di query con una tabella di destinazione
  • Un job di copia
  • Un'istruzione DDL ALTER TABLE
  • Un aggiornamento dei metadati della tabella (tables.update o tables.patch)

Per identificare la causa specifica e la soluzione, abbina il messaggio di errore a uno dei seguenti scenari.

Campo mancante nel nuovo schema

Messaggio di errore

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

Diagnosi

Una delle seguenti operazioni fornisce una definizione dello schema che omette una o più colonne già esistenti nella tabella di destinazione:

  • Un job di caricamento
  • Un'operazione di scrittura di DataFrame
  • Una chiamata API tables.update o tables.patch

Risoluzione

BigQuery non consente di eliminare le colonne in modo implicito omettendole da un payload dello schema dell'API o dalla configurazione di un job di caricamento. Per risolvere questo errore, esegui una delle seguenti operazioni:

  • Aggiorna la pipeline o la richiesta API in modo che lo schema fornito includa tutte le colonne esistenti nella tabella di destinazione.

  • Se intendi rimuovere la colonna dalla tabella, esegui un'istruzione DDL DROP COLUMN anziché omettere la colonna da una richiesta di caricamento o di patch:

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

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del progetto che contiene la tabella.
    • DATASET: il nome del set di dati che contiene la tabella.
    • TABLE: il nome della tabella.
    • FIELD_NAME: il nome della colonna da eliminare.

Il tipo di campo è stato modificato

Messaggio di errore

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

Diagnosi

La tua richiesta tenta di modificare il tipo di dati di una colonna esistente (ad esempio, da STRING a INT64) durante un job di caricamento o un aggiornamento dello schema.

Risoluzione

Per risolvere questo errore, esegui una delle seguenti operazioni:

  • Se la modifica del tipo è una conversione del tipo di dati della colonna supportata (ad esempio da INT64 a NUMERIC, da INT64 a FLOAT64 o da NUMERIC a BIGNUMERIC), utilizza un'istruzione DDL ALTER TABLE ... ALTER COLUMN:

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

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del progetto che contiene la tabella.
    • DATASET: il nome del set di dati che contiene la tabella.
    • TABLE: il nome della tabella.
    • FIELD_NAME: il nome della colonna da modificare.
    • NEW_TYPE: il tipo di dati di destinazione.

  • Se la conversione del tipo non è supportata in loco, esegui una query sui dati esistenti con un'espressione CAST esplicita e scrivi i risultati in una nuova tabella o sovrascrivi la tabella esistente. Per saperne di più, consulta Modifica il tipo di dati di una colonna.

La modalità del campo è cambiata

Messaggio di errore

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

Diagnosi

La tua richiesta tenta una modifica della modalità della colonna non supportata (ad esempio, la modifica di NULLABLE in REQUIRED o di REPEATED in NULLABLE). Questo errore si verifica anche se utilizzi una definizione di schema incorporato nello strumento a riga di comando bq quando disattivi una colonna REQUIRED in una tabella che contiene colonne REPEATED, perché le definizioni di schema incorporato nello strumento a riga di comando bq non supportano la modifica di tabelle con colonne REPEATED.

Risoluzione

L'unica modifica della modalità supportata dagli aggiornamenti dello schema BigQuery in loco è l'allentamento della modalità di una colonna da REQUIRED a NULLABLE. Per risolvere questo errore, esegui una delle seguenti operazioni:

  • Se stai modificando una colonna da REQUIRED a NULLABLE, esegui un'istruzione DDL ALTER TABLE ... ALTER COLUMN ... DROP NOT NULL in GoogleSQL o fornisci un file di schema JSON se stai aggiornando lo schema con il comando bq update o il metodo API tables.patch. Per istruzioni, consulta Modifica la modalità di una colonna.
  • Per modificare la modalità di una colonna da NULLABLE a REQUIRED o da REPEATED a NULLABLE, crea una nuova tabella con lo schema aggiornato e copia o carica i dati nella nuova tabella. Per istruzioni, consulta Modifica degli schemi delle tabelle.

Impossibile aggiungere campi

Messaggio di errore

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

Diagnosi

Un job di caricamento o di query include una colonna (FIELD_NAME) che non esiste nella tabella di destinazione e l'aggiunta dello schema non è abilitata nella configurazione del job.

Risoluzione

Abilita l'aggiunta dello schema nel job di caricamento o di query:

  • Nell'API REST o nelle librerie client, includi ALLOW_FIELD_ADDITION nella proprietà schemaUpdateOptions della configurazione del job di caricamento o di query.
  • Nello strumento a riga di comando bq, passa il flag --schema_update_option=ALLOW_FIELD_ADDITION.
  • In alternativa, aggiungi la colonna prima di eseguire il job utilizzando ALTER TABLE ... ADD COLUMN.

Impossibile aggiungere campi obbligatori a uno schema esistente

Messaggio di errore

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

Diagnosi

La tua richiesta aggiunge una nuova colonna a una tabella esistente con la modalità della colonna impostata su REQUIRED (NOT NULL). Poiché le righe esistenti nella tabella riceverebbero valori NULL per la colonna appena aggiunta, BigQuery rifiuta l'aggiunta di colonne REQUIRED direttamente tramite gli aggiornamenti dello schema.

Risoluzione

Per risolvere questo errore, esegui una delle seguenti operazioni:

  • Aggiungi la nuova colonna con la modalità NULLABLE anziché REQUIRED, quindi esegui un'istruzione DML UPDATE per compilare i valori per le righe esistenti.

  • Per aggiungere la colonna e assegnare un valore predefinito, completa i seguenti passaggi:

    1. Aggiungi la colonna come colonna NULLABLE.
    2. Imposta il valore predefinito della colonna in modo che i futuri inserimenti ricevano automaticamente un valore.

    3. Aggiorna le righe esistenti per inserire il valore predefinito:

      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;

      Sostituisci quanto segue:

      • PROJECT_ID: l'ID del progetto che contiene la tabella.
      • DATASET: il nome del set di dati che contiene la tabella.
      • TABLE: il nome della tabella.
      • FIELD_NAME: il nome della nuova colonna.
      • DATA_TYPE: il tipo di dati della colonna.
      • DEFAULT_EXPRESSION: l'espressione del valore predefinito per la colonna.

Il campo esiste già nello schema

Messaggio di errore

Field FIELD_NAME already exists in schema

Diagnosi

Lo schema fornito nella richiesta API, nel file di schema JSON o nell'intestazione del file di origine (ad esempio CSV o Parquet) contiene nomi di colonne duplicati. I nomi delle colonne in BigQuery non fanno distinzione tra maiuscole e minuscole, pertanto la specifica di Field_A e field_a nello stesso schema attiva questo errore.

Risoluzione

Esamina lo schema di origine e rimuovi o rinomina i nomi delle colonne duplicati, incluse eventuali collisioni di nomi senza distinzione tra maiuscole e minuscole.

L'aggiornamento della regole di confronto dei campi non è supportato

Messaggio di errore

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"

Diagnosi

Non puoi modificare o rimuovere la specifica di confronto di una colonna esistente durante un aggiornamento dello schema. Questo errore si verifica comunemente quando un'applicazione recupera lo schema di una tabella, modifica un altro campo e riscrive lo schema utilizzando una versione precedente della libreria client che non conserva la proprietà del campo collation (inviando "" anziché "und:ci").

Risoluzione

Per risolvere questo errore, segui questi passaggi:

  • Esegui l'upgrade della libreria client di BigQuery all'ultima versione in modo che gli attributi collation esistenti vengano conservati durante la lettura e l'applicazione di patch ai metadati della tabella.
  • Se crei manualmente i payload dello schema JSON, assicurati che la proprietà collation sulle colonne esistenti corrisponda allo schema attuale della tabella.

La limitazione dei parametri di tipo non è compatibile

Messaggio di errore

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

Diagnosi

L'istruzione ALTER TABLE ... ALTER COLUMN ... SET DATA TYPE tenta di ridurre la lunghezza, la precisione o la scala massima di un tipo di dati con parametri, ad esempio modificando STRING(100) in STRING(50) o riducendo i parametri NUMERIC(P, S).

Risoluzione

BigQuery consente solo di ampliare i parametri di tipo su una colonna esistente (ad esempio, aumentando STRING(50) a STRING(100)). Per applicare parametri di tipo più ristretti, crea una nuova tabella definita con il parametro di tipo più ristretto e copia o carica i dati nella nuova tabella utilizzando una query SELECT che adatti i valori al tipo più ristretto (ad esempio, LEFT(FIELD_NAME, 50) per una colonna STRING). La scrittura di un valore STRING o BYTES più lungo della lunghezza massima della colonna o di un valore NUMERIC con più cifre di quelle consentite dalla sua precisione restituisce un errore. I valori NUMERIC con più cifre decimali rispetto alla scala della colonna vengono arrotondati. Per saperne di più, consulta Modifica degli schemi delle tabelle.

L'aggiunta di un campo con un valore predefinito non è supportata

Messaggio di errore

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

Diagnosi

Il job di caricamento o la richiesta API tables.patch o tables.update tenta di aggiungere una nuova colonna a una tabella esistente specificando defaultValueExpression nel payload dello schema dell'API. Non puoi aggiungere una nuova colonna con un valore predefinito a una tabella esistente in un singolo aggiornamento dello schema dell'API.

Risoluzione

Anziché specificare defaultValueExpression quando aggiungi la colonna nella richiesta API, aggiungi prima la colonna e poi imposta il relativo valore predefinito (per ulteriori informazioni, consulta Limitazioni):

  • Se non hai ancora aggiunto la colonna, esegui le seguenti istruzioni, quindi riprendi i caricamenti senza 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;

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del progetto che contiene la tabella.
    • DATASET: il nome del set di dati che contiene la tabella.
    • TABLE: il nome della tabella.
    • FIELD_NAME: il nome della nuova colonna.
    • DATA_TYPE: il tipo di dati della colonna.
    • DEFAULT_EXPRESSION: l'espressione del valore predefinito per la colonna.

  • Se hai già aggiunto la colonna inviando nuovamente la richiesta senza defaultValueExpression, esegui solo le istruzioni ALTER COLUMN ... SET DEFAULT e UPDATE dell'esempio precedente.

L'aggiornamento degli attributi di una colonna di identità esistente non è supportato

Messaggio di errore

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.

Diagnosi

La tua richiesta tenta di modificare gli attributi di una colonna di identità esistente tramite un aggiornamento dello schema o una patch API.

Risoluzione

Le proprietà delle colonne di identità non possono essere modificate in loco dopo la creazione. Mantieni invariata la definizione della colonna di identità esistente nel payload di aggiornamento dello schema o crea una nuova tabella con la configurazione della colonna di identità aggiornata e copia o carica i dati nella nuova tabella. Per istruzioni, consulta Modifica degli schemi delle tabelle.

Modifica del campo incompatibile all'interno della colonna RECORD

Messaggio di errore

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

Diagnosi

L'istruzione ALTER TABLE ... ALTER COLUMN ... SET DATA TYPE specifica un tipo STRUCT non compatibile con il tipo esistente della colonna. Ad esempio, il nuovo tipo aggiunge o rimuove sottocampi, modifica un sottocampo in un tipo non supportato o restringe i parametri del tipo di un sottocampo.

Risoluzione

Confronta il tipo STRUCT nell'istruzione ALTER TABLE con lo schema esistente della colonna, quindi esegui una delle seguenti operazioni:

Limite massimo di schemi fisici divergenti raggiunto

Messaggio di errore

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

Diagnosi

Alcune modifiche allo schema della tabella, come l'eliminazione o la ridenominazione delle colonne, possono far sì che le tabelle abbiano schemi logici identici nell'API, ma rappresentazioni di schemi fisici sottostanti diverse. Quando copi i dati in una tabella di destinazione in troppe versioni di schema fisico divergenti, il job di copia della tabella può non riuscire con questo errore. Per ulteriori informazioni, consulta Limitazioni alla copia delle tabelle.

Risoluzione

Utilizza l'istruzione DDL CREATE TABLE LIKE per ricreare la tabella di destinazione in modo che la rappresentazione dello schema fisico corrisponda allo schema della tabella di origine, quindi copia o inserisci i dati:

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

Sostituisci quanto segue:

  • PROJECT_ID: l'ID del progetto che contiene le tabelle.
  • DATASET: il nome del set di dati che contiene le tabelle.
  • DESTINATION_TABLE: il nome della tabella di destinazione da ricreare.
  • SOURCE_TABLE: il nome della tabella di origine.

Risolvi gli errori relativi ai limiti di nidificazione di schemi, file e routine

BigQuery applica una profondità di nidificazione massima di 15 livelli per le colonne STRUCT (RECORD), i file di caricamento strutturati e i tipi di argomenti e tipi restituiti delle routine nidificate. Il superamento di questo limite di 15 livelli restituisce un errore HTTP 400 Bad Request con uno dei seguenti messaggi (dove MAX_DEPTH e MAX_LEVEL sono 15). Per gli errori causati dal superamento del limite di nidificazione di 16 livelli nelle viste logiche o nelle funzioni definite dall'utente permanenti, consulta Troppe viste nidificate o funzioni definite dall'utente permanenti.

Messaggi di errore

  • 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

Diagnosi

Le colonne di tipo STRUCT (RECORD) possono contenere campi RECORD nidificati fino a una profondità massima di 15 livelli, indipendentemente dal fatto che i campi siano scalari (NULLABLE o REQUIRED) o basati su array (REPEATED). Analogamente, i job di caricamento JSON, Parquet e Avro e le tabelle esterne applicano il limite di nidificazione quando analizzano le strutture nidificate. Per i file Parquet, il limite è espresso come livello di definizione massimo e livello di ripetizione massimo.

Negli errori delle routine, TYPE_DESCRIPTION identifica il tipo nidificato: argument type, return type o return table type.

Risoluzione

Questo limite non può essere aumentato. Per risolvere questo errore, esegui una delle seguenti operazioni:

  • Appiattisci lo schema o la definizione del tipo di routine. Suddividi le gerarchie STRUCT o ARRAY con nidificazione profonda nello schema della tabella o nei tipi di argomento e tipo restituito della routine in tabelle correlate separate e uniscile al momento della query oppure promuovi gli attributi con nidificazione profonda a colonne di livello superiore.
  • Utilizza il tipo di dati JSON integrato. Se i tuoi dati richiedono più di 15 livelli di nidificazione, archivia i sottoalberi nidificati in profondità in una colonna di tipo JSON (o STRING). Una colonna JSON viene archiviata come una singola colonna nello schema della tabella, evitando il limite di 15 livelli dello schema RECORD, consentendoti comunque di estrarre i percorsi nidificati in profondità al momento della query utilizzando operatori e funzioni di accesso ai campi JSON.
  • Pre-elabora i file di input prima del caricamento. Se l'errore si verifica durante un job di caricamento da file JSON, Parquet o Avro in Cloud Storage, aggiungi un passaggio di pre-elaborazione upstream per rendere flat o serializzare le strutture più profonde di 15 livelli prima di caricarle in BigQuery.