ALTER TABLE (Databricks SQL)

Modifica lo schema o le proprietà di una tabella.

Per le modifiche al tipo o la ridenominazione delle colonne in Delta Lake, vedere riscrivere i dati.

Per modificare il commento in una tabella, utilizzare COMMENT ON.

Se la tabella viene memorizzata nella cache, il comando cancella i dati memorizzati nella cache della tabella e tutti i relativi dipendenti che vi fanno riferimento. La cache verrà riempita in modo differibile quando si accede alla tabella o ai dipendenti la volta successiva.

Autorizzazioni necessarie

Se si usa il catalogo Unity, è necessario disporre MODIFY dell'autorizzazione per:

  • ALTER COLUMN
  • AGGIUNGI COLONNA
  • DROP COLUMN
  • SET TBLPROPERTIES
  • UNSET TBLPROPERTIES

Tutte le altre operazioni richiedono la proprietà della tabella.

Sintassi

ALTER TABLE table_name
   { RENAME TO clause |
     ADD COLUMN clause |
     ALTER COLUMN clause |
     DROP COLUMN clause |
     RENAME COLUMN clause |
     ADD CONSTRAINT clause |
     DROP CONSTRAINT clause |
     ADD PARTITION clause |
     DROP PARTITION clause |
     RENAME PARTITION clause |
     RECOVER PARTITIONS clause |
     SET TBLPROPERTIES clause |
     UNSET TBLPROPERTIES clause |
     SET LOCATION clause |
     SET OWNER TO clause }

Parametri

  • table_name

    Identifica la tabella da modificare. Il nome non deve includere una specifica temporale.

  • RINOMINA IN to_table_name

    Rinomina la tabella all'interno dello stesso schema.

  • AGGIUNGI COLONNA

    Questa clausola non è supportata per le JDBC origini dati.

    Aggiunge una o più colonne alla tabella o campi alle colonne esistenti in una tabella Delta Lake.

    { ADD [COLUMN | COLUMNS ]
      ( { { column_identifier | field_name } data_type
          [DEFAULT clause] [COMMENT comment] [FIRST | AFTER identifier]
          } [, ...] ) }
    
    • column_identifier

      Nome della colonna da aggiungere. Il nome deve essere univoco all'interno della tabella.

      A meno che FIRST non venga AFTER name o specificata la colonna o il campo verrà accodato alla fine.

    • field_name

      Nome completo del campo da aggiungere a una colonna esistente. Tutti i componenti del percorso del campo annidato devono esistere e il nome del campo stesso deve essere univoco.

    • DEFAULT default_expression

      Richiede:SQL Warehouse versione 2022.35 o successiva. Questa versione è disponibile nel canale Di anteprima.

      Definisce un DEFAULT valore per la colonna utilizzata su INSERT e MERGE ... INSERT quando la colonna non viene specificata.

      Se non viene specificato alcun valore predefinito, DEFAULT NULL è implicito per le colonne nullable.

      default_expression può essere composto da valori letterali e funzioni o operatori SQL predefiniti, ad eccezione di:

      default_expression non deve contenere alcuna sottoquery.

      DEFAULT è supportato per CSVle origini , JSON, PARQUETe ORC .

    • Data_type

      Specifica il tipo di dati della colonna o del campo. Non tutti i tipi di dati supportati da Azure Databricks sono supportati da tutte le origini dati.

    • Commento commento

      Valore letterale STRING facoltativo che descrive la colonna o il campo aggiunto.

    • FIRST

      Se specificata, la colonna verrà aggiunta come prima colonna della tabella oppure il campo verrà aggiunto come primo campo di nello struct contenitore.

    • Identificatore AFTER

      Se è stata specificata la colonna o il campo verrà aggiunto immediatamente dopo il campo o la colonna identifier.

  • ALTER COLUMN

    Modifica una proprietà o la posizione di una colonna.

    { { ALTER | CHANGE } [COLUMN] { column_identifier | field_name }
      { COMMENT comment |
        { FIRST | AFTER column_identifier } |
        { SET | DROP } NOT NULL |
        SET DEFAULT clause |
        DROP DEFAULT |
        SYNC IDENTITY } }
    
    • column_identifier

      Nome della colonna da modificare.

    • field_name

      Nome completo del campo da modificare. Tutti i componenti del percorso del campo annidato devono esistere.

    • Commento commento

      Modifica la descrizione della column_name colonna. comment deve essere un valore letterale STRING.

    • IDENTIFICATORE FIRST o AFTER

      Sposta la colonna dalla posizione corrente alla parte anteriore (FIRST) o immediatamente AFTER all'oggetto identifier. Questa clausola è supportata solo se table_name è una tabella Delta.

    • SET NOT NULL o DROP NOT NULL

      Modifica il dominio dei valori di colonna validi per escludere i SET NOT NULLvalori Null o includere valori DROP NOT NULLNull. Questa opzione è supportata solo per le tabelle Delta Lake. Delta Lake garantisce che il vincolo sia valido per tutti i dati esistenti e nuovi.

    • SYNC IDENTITY

      Sincronizzare i metadati di una colonna Identity con i dati effettivi. Quando si scrivono valori personalizzati in una colonna Identity, potrebbe non essere conforme ai metadati. Questa opzione valuta lo stato e aggiorna i metadati in modo che siano coerenti con i dati effettivi. Dopo questo comando, il valore Identity assegnato automaticamente successivo inizierà da start + (n + 1) * step, dove n è il valore più piccolo che soddisfa start + n * step >= max() (per un passaggio positivo).

      Questa opzione è supportata solo per le colonne Identity nelle tabelle Delta Lake.

    • DROP DEFAULT

      Richiede:SQL Warehouse versione 2022.35 o successiva. Questa versione è disponibile nel canale Di anteprima.

      Rimuove l'espressione predefinita dalla colonna. Per le colonne nullable equivale a SET DEFAULT NULL. Per le colonne definite con NOT NULL è necessario specificare un valore per ogni operazione futura INSERT

  • DEFAULT default_expression

    Richiede:SQL Warehouse versione 2022.35 o successiva. Questa versione è disponibile nel canale Di anteprima.

    Definisce un DEFAULT valore per la colonna utilizzata su INSERT e MERGE ... INSERT quando la colonna non viene specificata.

    Se non viene specificato DEFAULT NULL alcun valore predefinito è implicito per le colonne nullable.

    default_expression può essere composto da valori letterali, funzioni SQL predefinite o operatori ad eccezione di:

    default_expression non deve contenere una sottoquery.

    DEFAULT è supportato per CSVle origini , JSON, ORCe DELTA .

    Quando si definisce l'impostazione predefinita per una colonna appena aggiunta, l'impostazione predefinita si applica a tutte le righe preesistenti. Se il valore predefinito include una funzione non deterministica, rand ad esempio o current_timestamp il valore, viene calcolato una volta quando ALTER TABLE viene eseguito e applicato come costante alle righe preesistenti. Per le righe appena inserite, l'espressione predefinita viene eseguita una volta per ogni riga.

    Quando si imposta un valore predefinito usando ALTER COLUMN le righe esistenti non sono interessate da tale modifica.

  • Data_type

    Specifica il tipo di dati della colonna o del campo. Non tutti i tipi di dati supportati da Azure Databricks sono supportati da tutte le origini dati.

  • DROP COLUMN

    Importante

    Questa funzionalità è disponibile in anteprima pubblica.

    Eliminare una o più colonne o campi in una tabella Delta Lake.

    Quando si rilascia una colonna o un campo, è necessario eliminare vincoli di controllo dipendenti e colonne generate.

    Per i requisiti, vedere Mapping delle colonne in Azure Databricks.

    DROP [COLUMN | COLUMNS] [ IF EXISTS ] ( { {column_identifier | field_name} [, ...] )
    
    • IF EXISTS

      Quando si specifica IF EXISTS, Azure Databricks ignora un tentativo di eliminare colonne che non esistono. In caso contrario, l'eliminazione di colonne non esistenti causa un errore.

    • column_identifier

      Nome della colonna esistente.

    • field_name

      Nome completo di un campo esistente.

  • RINOMINA COLONNA

    Importante

    Questa funzionalità è disponibile in anteprima pubblica.

    Rinomina una colonna o un campo in una tabella Delta Lake.

    Quando si rinomina una colonna o un campo è necessario modificare i vincoli di controllo dipendenti e le colonne generate. Tutte le chiavi primarie e le chiavi esterne che usano la colonna verranno eliminate. Nel caso di chiavi esterne, è necessario disporre della tabella in cui è definita la chiave esterna.

    Per i requisiti, vedere Mapping delle colonne in Azure Databricks.

    RENAME COLUMN { column_identifier TO to_column_identifier|
                    field_name TO to_field_identifier }
    
  • AGGIUNGI VINCOLO

    Aggiunge un vincolo check, un vincolo di chiave esterna informativo o un vincolo di chiave primaria informativo alla tabella.

    Le chiavi esterne e le chiavi primarie non sono supportate per le tabelle nel hive_metastore catalogo.

  • VINCOLO DROP

    Elimina una chiave primaria, una chiave esterna o un vincolo di controllo dalla tabella.

  • AGGIUNGI PARTIZIONE

    Se specificato aggiunge una o più partizioni alla tabella. L'aggiunta di partizioni non è supportata per le tabelle Delta Lake.

    ADD [IF NOT EXISTS] { PARTITION clause [ LOCATION path ] } [...]
    
    • SE NON ESISTE

      Clausola facoltativa che indirizza Azure Databricks a ignorare l'istruzione se la partizione esiste già.

    • Clausola PARTITION

      Partizione da aggiungere. Le chiavi di partizione devono corrispondere al partizionamento della tabella e devono essere associate ai valori. Se la partizione esiste già un errore, a meno che IF NOT EXISTS non sia stato specificato.

    • Percorso LOCATION

      path deve essere un valore letterale STRING che rappresenta una posizione facoltativa che punta alla partizione.

      Se non viene specificato alcun percorso, la posizione verrà derivata dalla posizione della tabella e dalle chiavi di partizione.

      Se sono presenti file nel percorso in cui popolano la partizione e devono essere compatibili con l'oggetto della tabella e le data_source relative opzioni.

  • DROP PARTITION

    Se specificata questa clausola elimina una o più partizioni dalla tabella, facoltativamente eliminando eventuali file nei percorsi delle partizioni.

    Le tabelle Delta Lake non supportano l'eliminazione delle partizioni.

    DROP [ IF EXISTS ] PARTITION clause [, ...] [PURGE]
    
    • IF EXISTS

      Quando si specifica IF EXISTS Azure Databricks ignora un tentativo di eliminare partizioni che non esistono. In caso contrario, le partizioni non esistenti causano un errore.

    • Clausola PARTITION

      Specifica una partizione da eliminare. Se la partizione viene identificata parzialmente solo una sezione di partizioni viene eliminata.

    • EPURAZIONE

      Se impostato, il catalogo tabelle deve rimuovere i dati di partizione ignorando la cartella Cestino anche quando il catalogo ne ha configurato uno. L'opzione è applicabile solo per le tabelle gestite. È efficace solo quando:

      Il file system supporta una cartella Cestino. Il catalogo è stato configurato per spostare la partizione eliminata nella cartella Cestino. Non esiste una cartella Cestino in AWS S3, quindi non è efficace.

      Non è necessario eliminare manualmente i file dopo aver eliminato le partizioni.

  • RINOMINA PARTIZIONE

    Sostituisce le chiavi di una partizione.

    Le tabelle Delta Lake non supportano la ridenominazione delle partizioni.

    from_partition_clause RENAME TO to_partition_clause
    
  • RIPRISTINARE LE PARTIZIONI

    Questa clausola non si applica alle tabelle Delta Lake.

    Indica ad Azure Databricks di analizzare il percorso della tabella e aggiungere tutti i file alla tabella che sono stati aggiunti direttamente al file system.

  • SET TBLPROPERTIES

    Imposta o reimposta una o più proprietà definite dall'utente.

  • UNSET TBLPROPERTIES

    Rimuove una o più proprietà definite dall'utente.

  • SET LOCATION

    Sposta la posizione di una partizione o di una tabella.

    Delta Lake non supporta lo spostamento di singole partizioni di una tabella Delta Lake.

    [ PARTITION clause ] SET LOCATION path
    
    • Clausola PARTITION

      Facoltativamente, identifica la partizione per cui verrà modificata la posizione. Se si omette la denominazione di una partizione di Azure Databricks sposta la posizione della tabella.

    • Percorso LOCATION

      path deve essere un valore letterale STRING. Specifica la nuova posizione per la partizione o la tabella.

      I file nel percorso originale non verranno spostati nel nuovo percorso.

  • [ SET ] PROPRIETARIO A entità

    Trasferisce la proprietà della tabella a principal.

    SET è consentito come parola chiave facoltativa. Richiede:SQL Warehouse versione 2022.35 o successiva. Questa versione è disponibile nel canale Di anteprima.

Esempi

Per gli esempi di aggiunta e modifica di colonne delta Lake, vedere

-- RENAME table
> DESCRIBE student;
                col_name data_type comment
 ----------------------- --------- -------
                    name    string    NULL
                  rollno       int    NULL
                     age       int    NULL
 # Partition Information
              # col_name data_type comment
                     age       int    NULL

> ALTER TABLE Student RENAME TO StudentInfo;

-- After Renaming the table
> DESCRIBE StudentInfo;
                col_name data_type comment
 ----------------------- --------- -------
                    name    string    NULL
                  rollno       int    NULL
                     age       int    NULL
 # Partition Information
              # col_name data_type comment
                     age       int    NULL

-- RENAME partition
> SHOW PARTITIONS StudentInfo;
 partition
 ---------
    age=10
    age=11
    age=12

> ALTER TABLE default.StudentInfo PARTITION (age='10') RENAME TO PARTITION (age='15');

-- After renaming Partition
> SHOW PARTITIONS StudentInfo;
 partition
 ---------
    age=11
    age=12
    age=15

-- Add new columns to a table
> DESCRIBE StudentInfo;
                col_name data_type comment
 ----------------------- --------- -------
                    name    string    NULL
                  rollno       int    NULL
                     age       int    NULL
 # Partition Information
              # col_name data_type comment
                     age       int    NULL

> ALTER TABLE StudentInfo ADD columns (LastName string, DOB timestamp);

-- After Adding New columns to the table
> DESCRIBE StudentInfo;
                col_name data_type comment
 ----------------------- --------- -------
                    name    string    NULL
                  rollno       int    NULL
                LastName    string    NULL
                     DOB timestamp    NULL
                     age       int    NULL
 # Partition Information
              # col_name data_type comment
                     age       int    NULL

-- Add a new partition to a table
> SHOW PARTITIONS StudentInfo;
 partition
 ---------
    age=11
    age=12
    age=15

> ALTER TABLE StudentInfo ADD IF NOT EXISTS PARTITION (age=18);

-- After adding a new partition to the table
> SHOW PARTITIONS StudentInfo;
 partition
 ---------
    age=11
    age=12
    age=15
    age=18

-- Drop a partition from the table
> SHOW PARTITIONS StudentInfo;
 partition
 ---------
    age=11
    age=12
    age=15
    age=18

> ALTER TABLE StudentInfo DROP IF EXISTS PARTITION (age=18);

-- After dropping the partition of the table
> SHOW PARTITIONS StudentInfo;
 partition
 ---------
    age=11
    age=12
    age=15

-- Adding multiple partitions to the table
> SHOW PARTITIONS StudentInfo;
 partition
 ---------
    age=11
    age=12
    age=15

> ALTER TABLE StudentInfo ADD IF NOT EXISTS PARTITION (age=18) PARTITION (age=20);

-- After adding multiple partitions to the table
> SHOW PARTITIONS StudentInfo;
 partition
 ---------
    age=11
    age=12
    age=15
    age=18
    age=20

-- ALTER or CHANGE COLUMNS
> DESCRIBE StudentInfo;
                col_name data_type comment
+-----------------------+---------+-------
                    name    string    NULL
                  rollno       int    NULL
                LastName    string    NULL
                     DOB timestamp    NULL
                     age       int    NULL
 # Partition Information
              # col_name data_type comment
                     age       int    NULL

ALTER TABLE StudentInfo ALTER COLUMN name COMMENT "new comment";

--After ALTER or CHANGE COLUMNS
> DESCRIBE StudentInfo;
                col_name data_type     comment
 ----------------------- --------- -----------
                    name    string new comment
                  rollno       int        NULL
                LastName    string        NULL
                     DOB timestamp        NULL
                     age       int        NULL
 # Partition Information
              # col_name data_type     comment
                     age       int        NULL

-- RENAME COLUMN
> ALTER TABLE StudentInfo RENAME COLUMN name TO FirstName;

--After RENAME COLUMN
> DESCRIBE StudentInfo;
                col_name data_type     comment
 ----------------------- --------- -----------
               FirstName    string new comment
                  rollno       int        NULL
                LastName    string        NULL
                     DOB timestamp        NULL
                     age       int        NULL
 # Partition Information
              # col_name data_type     comment
                     age       int        NULL

-- Change the file Location
> ALTER TABLE dbx.tab1 PARTITION (a='1', b='2') SET LOCATION '/path/to/part/ways'

-- SET TABLE PROPERTIES
> ALTER TABLE dbx.tab1 SET TBLPROPERTIES ('winner' = 'loser');

-- DROP TABLE PROPERTIES
> ALTER TABLE dbx.tab1 UNSET TBLPROPERTIES ('winner');