ALTER TABLE (Databricks SQL)

Modifica el esquema o las propiedades de una tabla.

Para obtener información sobre cambios de tipo o cambios de nombre de las columnas en Delta Lake, consulte reescritura de los datos.

Para cambiar el comentario de una tabla, use COMMENT ON.

Si la tabla se almacena en caché, el comando borra los datos almacenados en caché de la tabla y todos los elementos dependientes que hacen referencia a ella. La memoria caché se rellenará en diferido cuando se acceda a la tabla o a los elementos dependientes la próxima vez.

Permisos necesarios

Si usa Unity Catalog, debe tener el permiso MODIFY para:

  • ALTER COLUMN
  • ADD COLUMN
  • DROP COLUMN
  • SET TBLPROPERTIES
  • UNSET TBLPROPERTIES

Todas las demás operaciones requieren la titularidad de la tabla.

Sintaxis

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 }

Parámetros

  • table_name

    Identifica la tabla que se va a modificar. El nombre no debe incluir una especificación temporal.

  • RENAME TO to_table_name

    Cambia el nombre de la tabla en el mismo esquema.

  • AGREGAR COLUMNA

    Esta cláusula no es compatible con los orígenes de datos JDBC.

    Agrega una o varias columnas a la tabla o campos a las columnas existentes en una tabla de Delta Lake.

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

      Nombre de la columna que se va a agregar. El nombre debe ser único en la tabla.

      A menos que se especifiquen FIRST o AFTER name, la columna o el campo se anexarán al final.

    • field_name

      Nombre completo del campo que se va a agregar a una columna existente. Todos los componentes de la ruta de acceso al campo anidado deben existir y el propio nombre del campo debe ser único.

    • DEFAULT default_expression

      Requiere:Versión 2022.35 del almacén de SQL o versiones posteriores. Esta versión está disponible en el canal de versión preliminar.

      Define un valor DEFAULT para la columna que se usa en INSERT y MERGE ... INSERT cuando no se especifica la columna.

      Si no se especifica ningún valor predeterminado, DEFAULT NULL estará implícito para las columnas que admiten un valor NULL.

      default_expression puede estar compuesto de literales y funciones u operadores de SQL integrados, excepto:

      default_expression tampoco debe contener ninguna subconsulta.

      DEFAULT es compatible con orígenes CSV, JSON, PARQUET y ORC.

    • data_type

      Especifica el tipo de datos de la columna o el campo. No todos los tipos de datos que admite Azure Databricks son compatibles con todos los orígenes de datos.

    • COMMENT comment

      Literal de cadena opcional que describe la columna o el campo agregados.

    • FIRST

      Si se especifica, la columna se agregará como primera columna en la tabla, o el campo se agregará como primer campo en la estructura que lo contiene.

    • Identificador AFTER

      Si se especifica, la columna o el campo se agregarán inmediatamente después del campo o la columna identifier.

  • ALTER COLUMN

    Cambia una propiedad o la ubicación de una columna.

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

      Nombre de la columna que se va a modificar.

    • field_name

      Nombre completo del campo que se va a modificar. Todos los componentes de la ruta de acceso al campo anidado deben existir.

    • COMMENT comment

      Cambia la descripción de la columna column_name. comment debe ser un literal de cadena.

    • IdentificadorFIRST o AFTER

      Mueve la columna desde su posición actual al frente (FIRST) o inmediatamente AFTER del identifier. Esta cláusula solo se admite si table_name es una tabla Delta.

    • SET NOT NULL o DROP NOT NULL

      Cambia el dominio de los valores de columna válidos para excluir valores NULL SET NOT NULL, o incluir valores NULL DROP NOT NULL. Esta opción solo se admite para tablas de Delta Lake. Delta Lake garantizará que la restricción sea válida para todos los datos nuevos y existentes.

    • SYNC IDENTITY

      Sincronice los metadatos de una columna de identidad con los datos reales. Si escribe valores propios en una columna de identidad, es posible que no cumpla los requisitos de los metadatos. Esta opción evalúa el estado de los metadatos y los actualiza para que sean coherentes con los datos reales. Después de este comando, el siguiente valor de identidad asignado automáticamente se iniciará a partir de start + (n + 1) * step, donde n es el menor valor que cumple los requisitos de start + n * step >= max() (para un paso positivo).

      Esta opción solo se admite para las columnas de identidad en las tablas de Delta Lake.

    • DROP DEFAULT

      Requiere:Versión 2022.35 del almacén de SQL o versiones posteriores. Esta versión está disponible en el canal de versión preliminar.

      Quita la expresión predeterminada de la columna. En el caso de las columnas que admiten un valor NULL, equivale a SET DEFAULT NULL. En el caso de las columnas que se definen con NOT NULL, debe proporcionar un valor en cada operación futura INSERT

  • DEFAULT default_expression

    Requiere:Versión 2022.35 del almacén de SQL o versiones posteriores. Esta versión está disponible en el canal de versión preliminar.

    Define un valor DEFAULT para la columna que se usa en INSERT y MERGE ... INSERT cuando no se especifica la columna.

    Si no se especifica ningún valor predeterminado, DEFAULT NULL estará implícito para las columnas que admiten un valor NULL.

    default_expression puede estar compuesto de literales y funciones u operadores de SQL integrados, excepto:

    default_expression tampoco debe contener ninguna subconsulta.

    DEFAULT es compatible con orígenes CSV, JSON, ORC y PARQUET.

    Cuando se define el valor predeterminado para una columna recién agregada, este se aplica a todas las filas preexistentes. Si el valor predeterminado incluye una función no determinista, como rand o current_timestamp, dicho valor se calculará una vez cuando se ejecute ALTER TABLE y se aplicará como una constante a las filas preexistentes. En el caso de las filas recién insertadas, la expresión predeterminada se ejecuta una vez por fila.

    Cuando se establece un valor predeterminado mediante ALTER COLUMNno afecta a las filas existentes.

  • data_type

    Especifica el tipo de datos de la columna o el campo. No todos los tipos de datos que admite Azure Databricks son compatibles con todos los orígenes de datos.

  • DROP COLUMN

    Importante

    Esta característica está en versión preliminar pública.

    Elimine una o varias columnas o campos en una tabla Delta Lake.

    Al eliminar una columna o un campo, debe eliminar las restricciones de comprobación de los elementos dependientes y las columnas generadas.

    Para conocer los requisitos, consulte Asignación de columnas en Azure Databricks.

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

      Al especificar IF EXISTS, Azure Databricks omite el intento de eliminar columnas que no existen. De lo contrario, la eliminación de columnas no existentes producirá un error.

    • column_identifier

      Nombre de la columna existente.

    • field_name

      Nombre completo de un campo existente.

  • RENAME COLUMN

    Importante

    Esta característica está en versión preliminar pública.

    Cambia el nombre de una columna o de un campo de una tabla de Delta Lake.

    Al cambiar el nombre de una columna o un campo, también debe cambiar las restricciones check de los elementos dependientes y las columnas generadas. Se eliminarán las claves principales y las claves externas que usen la columna. En el caso de las claves externas, debe ser el propietario de la tabla en la que se ha definido la clave externa.

    Para conocer los requisitos, consulte Asignación de columnas en Azure Databricks.

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

      El nombre existente de la columna.

    • to_column_identifier

      El nuevo identificador de columna. El identificador debe ser único dentro de la tabla.

    • field_name

      El nombre completo existente de un campo.

    • to_field_identifier

      El nuevo identificador de campo. El identificador debe ser único dentro de la estructura local.

  • ADD CONSTRAINT

    Agrega una restricción de comprobación, una restricción de clave externa informativa o una restricción de clave principal informativa a la tabla.

    No se admiten claves externas ni claves principales para las tablas del catálogo hive_metastore.

  • DROP CONSTRAINT

    Elimina una restricción PRIMARY KEY, FOREIGN KEY o CHECK de la tabla.

  • ADD PARTITION

    Si se especifica, agrega una o varias particiones a la tabla. No se admite la adición de particiones para tablas de Delta Lake.

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

      Cláusula opcional que indica a Azure Databricks que omita la instrucción si ya existe la partición.

    • Cláusula PARTITION

      Partición que se va a agregar. Las claves de partición deben coincidir con la creación de particiones de la tabla y estar asociadas a valores. Si la partición ya existe, se genera un error a menos que IF NOT EXISTS se haya especificado.

    • LOCATION path

      path debe ser un literal de cadena que represente una ubicación opcional que apunte a la partición.

      Si no se especifica ninguna ubicación, esta derivará de la ubicación de la tabla y las claves de partición.

      Si hay archivos presentes en la ubicación, rellenan la partición y deben ser compatibles con el data_source de la tabla y sus opciones.

  • DROP PARTITION

    Si se especifica, esta cláusula anula una o varias particiones de la tabla y, opcionalmente, elimina los archivos en las ubicaciones de las particiones.

    Las tablas de Delta Lake no admiten la anulación de particiones.

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

      Al especificar IF EXISTS, Azure Databricks omite el intento de anular particiones que no existen. De lo contrario, las particiones no existentes producirán un error.

    • Cláusula PARTITION

      Especifica una partición que se va a anular. Si la partición solo se identifica parcialmente, se anula un segmento de particiones.

    • PURGE

      Si se establece, el catálogo de tablas debe quitar los datos de partición mediante la omisión de la carpeta Papelera aunque el catálogo la haya configurado. La opción solo es aplicable a las tablas administradas. Solo es eficaz cuando:

      El sistema de archivos admite una carpeta Papelera. El catálogo se ha configurado para trasladar la partición descartada a la carpeta Papelera. No hay ninguna carpeta Papelera en AWS S3, por lo que no es eficaz.

      No es necesario eliminar manualmente los archivos después de quitar particiones.

  • RENAME PARTITION

    Reemplaza las claves de una partición.

    Las tablas de Delta Lake no admiten el cambio de nombre de las particiones.

    from_partition_clause RENAME TO to_partition_clause
    
  • RECOVER PARTITIONS

    Esta cláusula no se aplica a las tablas de Delta Lake.

    Indica a Azure Databricks que examine la ubicación de la tabla y agregue los archivos que se hayan agregado directamente al sistema de archivos a la tabla.

  • SET TBLPROPERTIES

    Este parámetro le permite establecer o restablecer una o más propiedades que defina el usuario.

  • UNSET TBLPROPERTIES

    Este parámetro quita una o más propiedades que defina el usuario.

  • SET LOCATION

    Traslada la ubicación de una partición o tabla.

    Delta Lake no admite el traslado de particiones individuales de una tabla de Delta Lake.

    [ PARTITION clause ] SET LOCATION path
    
    • Cláusula PARTITION

      Opcionalmente, identifica la partición para la que se va a cambiar la ubicación. Si se omite la asignación de nombre a una partición, Azure Databricks traslada la ubicación de la tabla.

    • LOCATION path

      path debe ser un literal de cadena. Especifica la nueva ubicación para la partición o tabla.

      Los archivos de la ubicación original no se trasladarán a la nueva ubicación.

  • [ SET ] OWNER TO principal

    Transfiere la propiedad de la tabla a principal.

    SET se permite como una palabra clave opcional. Requiere:Versión 2022.35 del almacén de SQL o versiones posteriores. Esta versión está disponible en el canal de versión preliminar.

Ejemplos

Para ver ejemplos de incorporación y modificación de columnas de Delta Lake, consulte

-- 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');